11# Fix GitHub Issue
22
3- @description End-to-end: plan, implement, test, PR, review, fix findings , and comment on a GitHub issue.
3+ @description End-to-end: plan, implement, test, review, fix, push , and PR for a GitHub issue.
44@arguments $ISSUE_NUMBER: GitHub issue number to fix
55
6- Read GitHub Issue #$ISSUE_NUMBER thoroughly. Understand the full
7- context: problem description, acceptance criteria, linked PRs,
8- and any discussion. Follow linked issues, referenced PRs, and
9- external documentation to build complete understanding before
10- planning.
6+ Read GitHub Issue #$ISSUE_NUMBER from the canonical repo
7+ (` gh issue view $ISSUE_NUMBER --repo <owner/name> ` ) thoroughly.
8+ Understand the full context: problem description, acceptance
9+ criteria, linked PRs, and any discussion. Follow linked issues,
10+ referenced PRs, and external documentation to build complete
11+ understanding before planning.
12+
13+ Detect the upstream repository: if a git remote named ` upstream `
14+ exists, use it as the canonical repo (fetch from it, base branches
15+ on it, and submit PRs to it). Otherwise, fall back to ` origin ` .
16+ Resolve the canonical repo's ` owner/name ` (e.g. from `git remote
17+ get-url upstream` ) and store it — use ` --repo <owner/name>` on
18+ every ` gh ` command (issue views, PR creation, issue comments) to
19+ ensure they target the correct repository. Run
20+ ` git fetch <upstream-remote> ` to ensure you are working with
21+ up-to-date code.
1122
1223Execute every step below sequentially. Do not stop or ask for
1324confirmation at any step.
1425
15- ## 1. Plan
26+ ## 1. Research (if needed)
27+
28+ Before planning, determine if the issue requires external context
29+ you don't already have — unfamiliar APIs, protocols, libraries,
30+ error messages, or domain-specific concepts. If so, use Exa
31+ (` mcp__exa__web_search_exa ` ) to search for:
32+
33+ - Official documentation for referenced libraries or APIs
34+ - Known solutions for the error messages or symptoms described
35+ - Implementation patterns used by similar projects
36+
37+ Skip this step for straightforward bugs where the fix is clear
38+ from the codebase alone.
39+
40+ ## 2. Plan
1641
1742Write a detailed implementation plan to ` plan-issue-$ISSUE_NUMBER.md `
1843in the repo root. The plan must:
@@ -23,75 +48,178 @@ in the repo root. The plan must:
2348- Call out risks or open questions
2449- Reference relevant code paths by file: line
2550
26- ## 2. Implement
51+ ## 3. Create branch
52+
53+ Create the working branch before writing any code so changes are
54+ never left uncommitted on main.
55+
56+ - Determine the branch prefix from the issue type: ` fix/ ` for
57+ bugs, ` feat/ ` for features, ` refactor/ ` for refactors, ` docs/ `
58+ for documentation. When ambiguous, use ` fix/ ` .
59+ - Create a branch named ` {prefix}issue-$ISSUE_NUMBER ` based on
60+ the upstream remote's main branch (e.g. ` upstream/main ` if the
61+ ` upstream ` remote exists, otherwise ` origin/main ` )
62+
63+ ## 4. Implement
2764
2865Implement the plan across all necessary files. Follow the
2966project's CLAUDE.md standards. Keep changes minimal and focused
30- on the issue requirements -- no speculative features.
67+ on the issue requirements — no speculative features.
68+
69+ Add tests for the changed behavior as part of implementation —
70+ tests are code, not a quality gate.
71+
72+ When stuck during implementation — a confusing error, an
73+ unfamiliar API, or an approach that isn't working — use Exa
74+ to search for solutions rather than spinning.
75+
76+ ## 5. Build, test, lint
77+
78+ ### 5a. Discover project checks (CI is the source of truth)
79+
80+ Before running anything, read the project's CI configuration to
81+ learn what the project * actually* runs. This takes priority over
82+ the fallback tables below.
83+
84+ 1 . ** Read CI workflows.** Scan ` .github/workflows/ ` for the main
85+ CI workflow (typically ` ci.yml ` , ` test.yml ` , or ` build.yml ` ).
86+ Extract:
87+ - Test commands with feature flags (e.g.
88+ ` cargo test --features foo,bar ` )
89+ - Lint/format commands with non-default flags
90+ - Any step that runs a command then checks ` git diff --exit-code `
91+ — these are ** codegen sync checks** (schema generation,
92+ snapshot updates, help text, etc.). Record the command.
93+ - Docs/site build commands (e.g. ` make site ` , ` mkdocs build ` )
94+ 2 . ** Read the Makefile** (if present). Cross-reference targets
95+ used in CI — these are the ones that matter.
96+ 3 . ** Read CLAUDE.md** (if present at repo root or ` .claude/ ` ).
97+ It may define project-specific quality gates.
98+
99+ Store the discovered commands. They override the fallback table
100+ for any overlapping step.
101+
102+ ### 5b. Run the quality pipeline
103+
104+ Detect the project language from manifest files (` Cargo.toml ` →
105+ Rust, ` pyproject.toml ` /` setup.py ` → Python, ` package.json ` →
106+ Node/TypeScript, ` go.mod ` → Go). A project may use multiple
107+ languages; run checks for each.
108+
109+ Run checks in this order. For each step, use the CI-discovered
110+ command if one was found; otherwise fall back to the default.
111+
112+ 1 . ** Build** — compile or bundle
113+ 2 . ** Test** — run the full test suite with the same feature flags
114+ CI uses. Iterate on failures until green.
115+ 3 . ** Lint and format** — fix any issues
116+ 4 . ** Extended checks** — per-language extras (see fallback table)
117+ 5 . ** Codegen sync** — for every codegen check discovered in 5a,
118+ run the command and verify ` git diff --exit-code ` . If the diff
119+ is non-empty, the generated files are stale — regenerate and
120+ stage them.
121+ 6 . ** Docs build** — if the changes touch documentation files and a
122+ docs build command exists, run it to verify the docs compile.
123+
124+ ### Fallback defaults (when CI config is absent or unclear)
125+
126+ ** Rust** (detected by ` Cargo.toml ` ):
127+
128+ | step | command |
129+ | --------------| ------------------------------------------------|
130+ | build | ` cargo build ` |
131+ | test | ` cargo test ` |
132+ | lint | ` cargo clippy -- --deny warnings ` |
133+ | format | ` cargo fmt --check ` |
134+ | supply chain | ` cargo deny check ` (if ` deny.toml ` exists) |
135+ | careful | ` cargo careful test ` (if ` cargo-careful ` installed) |
136+
137+ ** Python** (detected by ` pyproject.toml ` or ` setup.py ` ):
138+
139+ | step | command |
140+ | --------------| ------------------------------------------------|
141+ | test | ` pytest -q ` |
142+ | lint | ` ruff check ` |
143+ | format | ` ruff format --check ` |
144+ | types | ` ty check ` (or ` mypy ` if configured) |
145+ | supply chain | ` pip-audit ` |
146+
147+ ** Node/TypeScript** (detected by ` package.json ` ):
148+
149+ | step | command |
150+ | --------------| ------------------------------------------------|
151+ | build | per project (` npm run build ` , ` tsc ` , etc.) |
152+ | test | ` vitest ` (or project test script) |
153+ | lint | ` oxlint ` (or project lint script) |
154+ | format | ` oxfmt --check ` (or project format script) |
155+ | types | ` tsc --noEmit ` |
156+ | supply chain | ` pnpm audit --audit-level=moderate ` |
157+
158+ ** Go** (detected by ` go.mod ` ):
159+
160+ | step | command |
161+ | --------------| ------------------------------------------------|
162+ | build | ` go build ./... ` |
163+ | test | ` go test ./... ` |
164+ | lint | ` golangci-lint run ` |
165+ | format | ` gofmt -l . ` |
166+ | vet | ` go vet ./... ` |
167+
168+ If a tool is not installed, skip it with a note rather than
169+ failing the pipeline.
31170
32- ## 3. Build, test, lint
171+ ## 6. Self-review
33172
34- Run the project's full quality pipeline in this order:
173+ For docs-only changes, do a focused manual review (verify links,
174+ check prose accuracy, confirm rendering). For code changes, use
175+ ` /pr-review-toolkit:review-pr ` to run a deep review against the
176+ diff (compare working tree to the upstream main branch). Produce a
177+ list of findings ranked by severity (P1 = blocks merge,
178+ P2 = important, P3 = nice to have).
35179
36- 1 . Build (compile/bundle if the project has a build step)
37- 2 . Run the full test suite -- iterate on failures until green
38- 3 . Add new tests for the changed behavior
39- 4 . Run linting, formatting, and type-checking -- fix any issues
180+ ## 7. Fix findings
40181
41- Refer to the project's CLAUDE.md or package.json/Makefile/etc.
42- for the correct commands.
182+ Address all P1–P3 findings. For each finding, either:
43183
44- ## 4. Branch, commit, and push
184+ - ** Fix it** — apply the change, or
185+ - ** Dismiss it** — explain why it's a false positive or not worth
186+ the churn (e.g. a stylistic disagreement or an impossible edge
187+ case). Document the reasoning inline.
45188
46- - Determine the branch prefix from the issue type: ` fix/ ` for
47- bugs, ` feat/ ` for features, ` refactor/ ` for refactors, ` docs/ `
48- for documentation. When ambiguous, use ` fix/ ` .
49- - Create a branch named ` {prefix}issue-$ISSUE_NUMBER `
50- - Delete the plan file (` plan-issue-$ISSUE_NUMBER.md ` ) -- it was a
189+ After addressing all findings, review your own fixes: read the
190+ diff of changes made in this step and verify each fix is correct,
191+ doesn't introduce new issues, and doesn't regress other parts of
192+ the implementation. If you spot a problem, fix it before
193+ proceeding.
194+
195+ Then re-run the full quality pipeline (build, test, lint). Iterate
196+ until clean.
197+
198+ ## 8. Commit and push
199+
200+ - Delete the plan file (` plan-issue-$ISSUE_NUMBER.md ` ) — it was a
51201 working artifact and should not be committed
52202- Commit all changes with a conventional commit message referencing
53203 the issue
54204- Push the branch
55205
56- ## 5 . Create PR
206+ ## 9 . Create PR
57207
58208Create a PR with:
59209
60210- A concise title (under 70 chars)
61211- A description that maps changes back to the issue requirements
62212- Link to the issue with "Closes #$ISSUE_NUMBER" (or "Refs" if it
63213 doesn't fully close it)
214+ - If an ` upstream ` remote exists, submit the PR to the upstream
215+ repo using ` gh pr create --repo <upstream-owner/repo> `
64216
65- ## 6. Self-review
66-
67- Use ` /compound-engineering:workflows:review ` to perform a full
68- multi-agent code review of the PR. Produce a list of findings
69- ranked by severity (P1 = blocks merge, P2 = important, P3 = nice
70- to have).
71-
72- ## 7. Fix findings
73-
74- Address all P1-P3 findings. For each finding, either:
75-
76- - ** Fix it** -- apply the change, or
77- - ** Dismiss it** -- explain why it's a false positive or not worth
78- the churn (e.g. a stylistic disagreement or an impossible edge
79- case). Document the reasoning inline.
80-
81- After addressing all findings:
82-
83- 1 . Re-run the full quality pipeline (build, test, lint)
84- 2 . Commit the fixes as a separate commit (do not squash into the
85- original -- preserve review history)
86- 3 . Push the branch (regular push, not force-push)
87- 4 . Delete any todo files in ` todos/ ` that were created by the
88- review and are now resolved
89-
90- ## 8. Comment on issue
217+ ## 10. Comment on issue
91218
92- Post a summary comment on Issue #$ISSUE_NUMBER linking to the PR.
93- Include:
219+ Post a summary comment on Issue #$ISSUE_NUMBER in the canonical
220+ repo (` gh issue comment $ISSUE_NUMBER --repo <owner/name> ` )
221+ linking to the PR. Include:
94222
95- - What was implemented (1- 3 bullet points)
223+ - What was implemented (1– 3 bullet points)
96224- Key design decisions
97225- Link to the PR
0 commit comments