# 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 `) 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 ` on every `gh` command (issue views, PR creation, issue comments) to ensure they target the correct repository. Run `git fetch ` 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 `mypy` if configured) | | supply chain | `pip-audit` | **Node/TypeScript** (detected by `package.json`): | step | command | |--------------|------------------------------------------------| | build | per project (`npm run build`, `tsc`, etc.) | | test | `vitest` (or project test script) | | lint | `oxlint` (or project lint script) | | format | `oxfmt --check` (or project format script) | | types | `tsc --noEmit` | | supply chain | `pnpm audit --audit-level=moderate` | **Go** (detected by `go.mod`): | step | command | |--------------|------------------------------------------------| | build | `go build ./...` | | test | `go test ./...` | | lint | `golangci-lint run` | | format | `gofmt -l .` | | vet | `go vet ./...` | If a tool is not installed, skip it with a note rather than failing the pipeline. ## 6. Self-review For docs-only changes, do a focused manual review (verify links, check prose accuracy, confirm rendering). For code changes, use `/pr-review-toolkit:review-pr` to run a deep review against the diff (compare working tree to the upstream main branch). Produce a list of findings ranked by severity (P1 = blocks merge, P2 = important, P3 = nice to have). ## 7. Fix findings Address all P1–P3 findings. For each finding, either: - **Fix it** — apply the change, or - **Dismiss it** — explain why it's a false positive or not worth the churn (e.g. a stylistic disagreement or an impossible edge case). Document the reasoning inline. After addressing all findings, review your own fixes: read the diff of changes made in this step and verify each fix is correct, doesn't introduce new issues, and doesn't regress other parts of the implementation. If you spot a problem, fix it before proceeding. Then re-run the full quality pipeline (build, test, lint). Iterate until clean. ## 8. Commit and push - Delete the plan file (`plan-issue-$ISSUE_NUMBER.md`) — it was a working artifact and should not be committed - Commit all changes with a conventional commit message referencing the issue - Push the branch ## 9. Create PR Create a PR with: - A concise title (under 70 chars) - A description that maps changes back to the issue requirements - Link to the issue with "Closes #$ISSUE_NUMBER" (or "Refs" if it doesn't fully close it) - If an `upstream` remote exists, submit the PR to the upstream repo using `gh pr create --repo ` ## 10. Comment on issue Post a summary comment on Issue #$ISSUE_NUMBER in the canonical repo (`gh issue comment $ISSUE_NUMBER --repo `) linking to the PR. Include: - What was implemented (1–3 bullet points) - Key design decisions - Link to the PR