/fix-issue

Fix GitHub Issue

@description End-to-end: plan, implement, test, review, fix, push, and PR for a GitHub issue. @arguments $ISSUE_NUMBER: GitHub issue number to fix

Read GitHub Issue #$ISSUE_NUMBER from the canonical repo (`gh issue view $ISSUE_NUMBER --repo <owner/name>`) thoroughly. Understand the full context: problem description, acceptance criteria, linked PRs, and any discussion. Follow linked issues, referenced PRs, and external documentation to build complete understanding before planning.

Detect the upstream repository: if a git remote named `upstream` exists, use it as the canonical repo (fetch from it, base branches on it, and submit PRs to it). Otherwise, fall back to `origin`. Resolve the canonical repo's `owner/name` (e.g. from `git remote get-url upstream`) and store it — use `--repo <owner/name>` on every `gh` command (issue views, PR creation, issue comments) to ensure they target the correct repository. Run `git fetch <upstream-remote>` to ensure you are working with up-to-date code.

Execute every step below sequentially. Do not stop or ask for confirmation at any step.

1. Research (if needed)

Before planning, determine if the issue requires external context you don't already have — unfamiliar APIs, protocols, libraries, error messages, or domain-specific concepts. If so, use Exa (`mcp__exa__web_search_exa`) to search for:

• Official documentation for referenced libraries or APIs
• Known solutions for the error messages or symptoms described
• Implementation patterns used by similar projects

Skip this step for straightforward bugs where the fix is clear from the codebase alone.

2. Plan

Write a detailed implementation plan to `plan-issue-$ISSUE_NUMBER.md` in the repo root. The plan must:

• Summarize the issue requirements
• List every file to create or modify
• Describe the approach and key design decisions
• Call out risks or open questions
• Reference relevant code paths by file:line

3. Create branch

Create the working branch before writing any code so changes are never left uncommitted on main.

• Determine the branch prefix from the issue type: `fix/` for

bugs, `feat/` for features, `refactor/` for refactors, `docs/` for documentation. When ambiguous, use `fix/`.

• Create a branch named `{prefix}issue-$ISSUE_NUMBER` based on

the upstream remote's main branch (e.g. `upstream/main` if the `upstream` remote exists, otherwise `origin/main`)

4. Implement

Implement the plan across all necessary files. Follow the project's CLAUDE.md standards. Keep changes minimal and focused on the issue requirements — no speculative features.

Add tests for the changed behavior as part of implementation — tests are code, not a quality gate.

When stuck during implementation — a confusing error, an unfamiliar API, or an approach that isn't working — use Exa to search for solutions rather than spinning.

5. Build, test, lint

5a. Discover project checks (CI is the source of truth)

Before running anything, read the project's CI configuration to learn what the project *actually* runs. This takes priority over the fallback tables below.

1. **Read CI workflows.** Scan `.github/workflows/` for the main CI workflow (typically `ci.yml`, `test.yml`, or `build.yml`). Extract:

• Test commands with feature flags (e.g.

`cargo test --features foo,bar`)

• Lint/format commands with non-default flags
• Any step that runs a command then checks `git diff --exit-code`

— these are **codegen sync checks** (schema generation, snapshot updates, help text, etc.). Record the command.

• Docs/site build commands (e.g. `make site`, `mkdocs build`)

2. **Read the Makefile** (if present). Cross-reference targets used in CI — these are the ones that matter. 3. **Read CLAUDE.md** (if present at repo root or `.claude/`). It may define project-specific quality gates.

Store the discovered commands. They override the fallback table for any overlapping step.

5b. Run the quality pipeline

Detect the project language from manifest files (`Cargo.toml` → Rust, `pyproject.toml`/`setup.py` → Python, `package.json` → Node/TypeScript, `go.mod` → Go). A project may use multiple languages; run checks for each.

Run checks in this order. For each step, use the CI-discovered command if one was found; otherwise fall back to the default.

1. **Build** — compile or bundle 2. **Test** — run the full test suite with the same feature flags CI uses. Iterate on failures until green. 3. **Lint and format** — fix any issues 4. **Extended checks** — per-language extras (see fallback table) 5. **Codegen sync** — for every codegen check discovered in 5a, run the command and verify `git diff --exit-code`. If the diff is non-empty, the generated files are stale — regenerate and stage them. 6. **Docs build** — if the changes touch documentation files and a docs build command exists, run it to verify the docs compile.

Fallback defaults (when CI config is absent or unclear)

**Rust** (detected by `Cargo.toml`):

| step | command | |--------------|------------------------------------------------| | build | `cargo build` | | test | `cargo test` | | lint | `cargo clippy -- --deny warnings` | | format | `cargo fmt --check` | | supply chain | `cargo deny check` (if `deny.toml` exists) | | careful | `cargo careful test` (if `cargo-careful` installed) |

**Python** (detected by `pyproject.toml` or `setup.py`):

| step | command | |--------------|------------------------------------------------| | test | `pytest -q` | | lint | `ruff check` | | format | `ruff format --check` | | types | `ty check` (or `m