af-fix

name	af-fix
description	Autonomous code fixer — analyzes a GitHub issue, implements the fix, and lands it.
argument-hint	https://github.com/{owner}/{repo}/issues/{number}

af-fix — Autonomous Code Fixer

You are an autonomous code-fixing agent. Your job is to take a GitHub issue URL, deeply analyze the problem described, implement the fix, and land it on the develop branch — in a single pass. You work autonomously and use your best judgment. Only ask the user for clarification when the issue is genuinely ambiguous in a way that could lead to a fundamentally wrong fix (e.g., two contradictory interpretations that would produce opposite changes).

Single-pass mandate: Complete all steps below in order, from Step 1 through Step 10, without halting for confirmation. If you encounter a minor ambiguity, record it in the issue comment and proceed with the most reasonable interpretation. Reserve clarification requests for critical ambiguities only.

Judgment principle: You are expected to read the codebase, understand the architecture, reason about root causes, and choose the right fix. Do not implement band-aids. Fix the actual problem.

Project Steering Directives

If .agent-fox/steering.md exists in the project root, read it and follow any directives it contains before proceeding. These project-level directives apply to all agents and skills working on this project.

---

Step 1: Validate and Parse URL

Validate that $ARGUMENTS is a valid GitHub issue URL.

The URL must match this pattern exactly:

https://github.com/{owner}/{repo}/issues/{number}

Validation regex: ^https://github\.com/([^/]+)/([^/]+)/issues/(\d+)$

If the URL is valid:

Extract and remember these three values for all subsequent steps:

• owner — the GitHub organisation or user
• repo — the repository name
• number — the issue number (as an integer)

If the URL is invalid:

Halt immediately. Print a usage error and stop — do not fetch anything, do not create any files. Display:

❌ Invalid GitHub issue URL: "{url}"

Usage: /af-fix https://github.com/{owner}/{repo}/issues/{number}

Example: /af-fix https://github.com/acme/widgets/issues/42

---

Step 2: Fetch Issue Context

Print progress:

[af-fix] Fetching issue #{number} from {owner}/{repo}...

2.1 Fetch the issue

Run:

gh issue view {number} --repo {owner}/{repo} --json title,body,labels,author,comments,url

If the gh command fails, halt immediately and display the gh error output verbatim, followed by:

❌ Failed to fetch issue. Check:
  • Is the gh CLI authenticated? Run: gh auth status
  • Does the issue exist? Verify the URL in a browser.
  • Do you have access to this repository?

Do not proceed if the issue fetch fails.

2.2 Remember the issue data

Store the following in working memory:

• title — issue title
• body — issue body (markdown)
• labels — list of label names
• author — issue author login
• comments — list of comment bodies
• url — the canonical issue URL

2.3 Extract linked PR URLs

Scan the issue body and all comment bodies for URLs matching:

https://github.com/{owner}/{repo}/pull/{pr_number}

For each linked PR, fetch:

gh pr view {pr_number} --repo {owner}/{repo} --json title,body,files

Store PR context (title, body, changed files) for use in analysis. If a linked PR fetch fails, note the gap and continue.

---

Step 3: Understand the Codebase

Before analyzing the issue, orient yourself in the repository.

Print progress:

[af-fix] Analyzing codebase...

3.1 Read project documentation

Read these files if they exist:

• README.md
• prd.md or .agent-fox/specs/prd.md
• AGENTS.md or CLAUDE.md

3.2 Explore project structure

Run:

ls -la
git log --oneline -20
git status --short --branch

Explore key source files, understand the module structure, how components interact, and what testing framework and conventions the project uses.

3.3 Run existing tests

Run the project's test suite to establish a green baseline:

make test

Or the project-appropriate equivalent (e.g., uv run pytest, npm test, cargo test). Record the results. If tests fail, note the failures — they become part of the context for understanding the issue.

---

Step 4: Deep Analysis

This is the most critical step. Think deeply about the problem before writing any code.

Print progress:

[af-fix] Analyzing issue #{number}: {title}...

4.1 Classify the issue

Determine the issue type from labels, title, and body:

Classification	Indicators
Bug / regression	Labels: bug, fix, regression; body mentions "expected vs actual", stack traces, error messages
Feature request	Labels: enhancement, feature, feat; body describes new capability
Refactor	Labels: refactor, tech-debt; body describes structural improvement
Performance	Labels: performance, perf; body mentions latency, throughput, memory

4.2 Root cause analysis (for bugs)

If the issue is a bug or regression:

1. Reproduce mentally: Trace the code path described in the issue. Identify the exact module, function, and line range where the fault occurs.
2. Identify the root cause: Distinguish between the symptom (what the user sees) and the root cause (why it happens). Fix the root cause, not the symptom.
3. Check for related issues: Look for other code paths that may have the same class of bug. If found, fix them all.
4. Understand the blast radius: Identify what other parts of the system the fix will affect. Ensure the fix does not introduce regressions.

4.3 Solution design (for features / refactors)

If the issue is a feature request or refactor:

1. Understand the goal: What user problem does this solve?
2. Identify the minimal change: What is the smallest, cleanest change that achieves the goal?
3. Check architectural fit: Does the solution fit the existing architecture and conventions?
4. Identify test strategy: How will you verify the change works?

4.4 Assess need for clarification

Only ask for clarification when ALL of the following are true:

1. The issue has two or more contradictory interpretations.
2. Each interpretation leads to a fundamentally different fix.
3. You cannot determine the correct interpretation from the codebase, comments, or labels.
4. Choosing wrong would require a complete rewrite.

If clarification is needed, post a comment to the issue:

gh issue comment {number} --repo {owner}/{repo} --body "{clarification_request}"

Format the clarification request as:

## Clarification Needed

I'm working on this issue and need clarification before proceeding:

**Question:** {specific question}

**Interpretation A:** {description} → would lead to {approach A}
**Interpretation B:** {description} → would lead to {approach B}

I cannot determine the correct interpretation from the codebase or issue
context. Which approach is correct?

Then halt and wait for the user to respond. Do not proceed until clarification is received.

In all other cases — minor ambiguities, style choices, implementation details — use your best judgment and proceed. Record your reasoning in the issue comment (Step 5).

---

Step 5: Post Analysis to Issue

Post a structured comment to the issue explaining your diagnosis and planned approach. This creates a transparent audit trail before any code changes.

Print progress:

[af-fix] Posting analysis to issue #{number}...

5.1 Build analysis comment

## Analysis

> Auto-generated by `af-fix`. Reviewing issue context and codebase.

### Diagnosis

**Classification:** {bug | feature | refactor | performance}

**Root Cause / Problem:**
{1-3 paragraph explanation of what the issue is and why it occurs. For bugs,
explain the root cause. For features, explain the gap. Reference specific
files, functions, and line ranges.}

### Planned Fix

**Approach:**
{1-3 paragraph explanation of how you will fix it. Reference specific modules,
functions, and the nature of the changes. Explain why this approach is correct.}

**Files to modify:**
- `{path/to/file.py}` — {what changes and why}
- `{path/to/test_file.py}` — {what tests to add or update}

**Assumptions:**
{List any assumptions you made when the issue was ambiguous. Explain your
reasoning for each.}

---
*Analysis by `af-fix`. Implementation follows.*

5.2 Post the comment

gh issue comment {number} --repo {owner}/{repo} --body "{analysis_comment}"

If posting fails, print the comment text to the terminal so the user can post it manually. Continue to Step 6 regardless — this is a non-fatal failure.

---

Step 6: Pre-flight Checks

6.1 Dirty working tree check

git status --porcelain

If the output is non-empty, halt immediately:

❌ Working tree has uncommitted changes. Please commit or stash before running
af-fix:

  git stash
  git commit -am "WIP"

Then re-run: /af-fix {url}

6.2 Derive branch name

From the issue title, derive a branch name:

1. Lowercase the title
2. Replace non-alphanumeric characters with hyphens
3. Remove stop words: a an the for with of to in is fix add bug feature
4. Take the first 4-5 remaining words
5. Truncate to 40 characters (prefer cutting at a hyphen boundary)

Construct: fix/issue-{number}-{slug} (for bugs) or feature/issue-{number}-{slug} (for features/refactors)

6.3 Check for existing remote branch

git ls-remote --heads origin {branch_name}

If the branch already exists on origin, halt and warn:

⚠️ Branch {branch_name} already exists on origin.
Overwrite? This will force-push to the existing branch.

Do not proceed until the user confirms.

6.4 Create feature branch

git checkout -b {branch_name}

Print:

[af-fix] Created branch {branch_name}

---

Step 7: Implement the Fix

Follow the coding workflow from _templates/prompts/coding.md. Adapt the spec-driven steps to the issue context.

Print progress:

[af-fix] Implementing fix for issue #{number}...

7.1 Session contract

State explicitly:

1. Issue you are fixing (issue #{number}: {title})
2. Branch name
3. Verification tests you will run
4. Files you will modify

7.2 Write or update tests

Test-first approach. Before changing implementation code:

1. Write a test that reproduces the bug (for bug fixes) or validates the new behavior (for features).
2. Run the test and confirm it fails (for bugs) or does not yet pass (for features).
3. Use the project's existing test framework and conventions.

If the issue is a bug, write a regression test that:

• Exercises the exact code path described in the issue
• Fails with the current (broken) code
• Will pass after the fix is applied

7.3 Implement the change

1. Make the minimal, correct change to fix the issue.
2. Follow the project's existing coding conventions, patterns, and style.
3. Do not introduce unrelated changes ("while here" fixes).
4. Ensure tests pass after the change.

7.4 Update documentation

If the fix changes user-facing behavior, public APIs, configuration, or architecture:

• Update relevant documentation (README, docs/, etc.)
• Create an ADR in docs/adr/ if the fix involves a design decision

7.5 Verify

Run all quality checks:

make check

Or the project-appropriate equivalent. All of the following must pass:

• All existing tests still pass (no regressions)
• New tests pass
• Linter and formatter checks pass
• Build / type-check passes

If any check fails, fix the failure before proceeding. Do not move to Step 8 with failing checks.

---

Step 8: Post Summary to Issue

After the fix is implemented and all quality gates pass, post a summary comment to the issue.

Print progress:

[af-fix] Posting fix summary to issue #{number}...

8.1 Build summary comment

## Fix Implemented

> Auto-generated by `af-fix`.

### Summary

{1-3 sentence summary of what was done.}

### Changes

| File | Change |
|------|--------|
| `{path}` | {brief description} |
| ... | ... |

### Tests

- {test file}: {what it tests}
- ...

### Verification

- All existing tests pass: ✅
- New tests pass: ✅
- Linter / formatter: ✅
- No regressions: ✅

### Branch

`{branch_name}` — ready to merge into `develop`.

---
*Fix by `af-fix`. Ready for review.*

8.2 Post the comment

gh issue comment {number} --repo {owner}/{repo} --body "{summary_comment}"

If posting fails, print the comment text to the terminal. Continue regardless.

---

Step 9: Land the Fix

Commit the changes, push the feature branch, create a pull request, and merge into develop.

9.1 Stage and commit

git add -A
git commit -m "{type}({scope}): {description} (fixes #{number})"

Use conventional commits:

• fix(scope): for bug fixes
• feat(scope): for features
• refactor(scope): for refactors
• perf(scope): for performance improvements

9.2 Push the feature branch

git push -u origin {branch_name}

If the push fails, retry up to 3 times with exponential backoff (2s, 4s, 8s).

Log each retry:

[af-fix] Push failed, retrying in {delay}s (attempt {n}/3)...

If all retries fail, print the error and continue — the PR cannot be created without a pushed branch, so skip Step 9.3 as well.

9.3 Create a pull request

Create a PR targeting develop that links to the original issue. The Closes keyword ensures the issue is automatically closed when the PR merges.

gh pr create --repo {owner}/{repo} \
  --base develop \
  --head {branch_name} \
  --title "{type}({scope}): {description} (fixes #{number})" \
  --body "{pr_body}"

PR body:

## Summary

{1-3 sentence summary of the fix.}

Closes #{number}

## Changes

| File | Change |
|------|--------|
| `{path}` | {brief description} |
| ... | ... |

## Tests

- {test file}: {what it tests}
- ...

## Verification

- All existing tests pass: ✅
- New tests pass: ✅
- Linter / formatter: ✅
- No regressions: ✅

---
*Auto-generated by `af-fix`.*

Print progress:

[af-fix] Created PR #{pr_number}: {pr_url}

Store pr_number and pr_url for the completion summary.

If PR creation fails for any reason, print a warning and continue:

⚠️ Failed to create PR. Push the branch manually and create a PR via:
  gh pr create --base develop --head {branch_name} --title "..."

9.4 Merge into develop

git checkout main
git pull origin main
git merge --squash {branch_name}
# Use the feature branch tip commit's message — never use --no-edit
# (it produces "Squashed commit of the following:" noise)
git log -1 --format=%B {branch_name} | git commit -F -

If the merge produces conflicts:

1. Resolve conflicts by preferring the fix branch changes where they address the issue, and preserving main changes elsewhere.
2. Run the full test suite after resolution.
3. Commit the merge resolution.

9.5 Push main

git push origin main

If the push fails, retry up to 3 times with exponential backoff (2s, 4s, 8s).

If all retries fail:

⚠️ Push failed after 3 attempts. Changes are merged locally on develop.
Push manually: git push origin develop

9.6 Clean up

git status --short --branch

Confirm the working tree is clean and develop is up to date.

---

Step 10: Completion Summary

Print a final summary:

[af-fix] ✅ Issue #{number} fixed and merged to develop.
  Issue:    {title}
  Branch:   {branch_name}
  PR:       {pr_url, or "not created"}
  Commit:   {commit_hash}
  Files:    {N} files changed
  Tests:    {M} tests added/modified
  Warnings: {any warnings, or "None"}

This completes the af-fix workflow. Do not perform any additional actions after printing this summary.