| name | resolve-bug |
| description | Orchestrates the full bugfix pipeline for a BUG-XXX or GitHub issue: an isolated tester reproduces the bug and updates the issue, a senior-dev agent writes a root-cause fix plan while a business-analyst agent links the affected requirement(s) in parallel, then the fix is implemented and gated on Definition of Done. Use when the user asks to "fix this bug", "resolve BUG-XXX", "run the bugfix pipeline", pastes a GitHub issue link and asks to fix it, or mentions an end-to-end bug resolution workflow.
|
Resolve Bug Pipeline
Instructions
Run the complete bugfix pipeline for $ARGUMENTS — a bug ID (BUG-XXX), a GitHub issue URL
(e.g. https://github.com/owner/repo/issues/47), or a bare issue number.
This orchestrates four roles in sequence/parallel: Tester (reproduce) → Senior Dev
Analyst + Business Analyst (in parallel: fix plan / requirement linking) → Senior Dev
(implement the fix). Each isolated role runs as a typed subagent with no visibility into the
others' reasoning, so findings are independent, not rationalized.
Prerequisites
docs/requirements.md and docs/use_cases/ (from core skills) — used by the
requirement-linker agent.- A
BUG-XXX doc, or a GitHub issue that one can be created from (see Step 0).
DO NOT
- Skip the reproduction step, even if the bug "obviously" still exists — the tester's evidence
is what the fix plan and the fix itself are grounded in
- Proceed to Step 2 or Step 3 if the tester reports Not Reproducible
- Let the
bug-analyst or requirement-linker agents edit implementation files — they analyze
and link only; only Step 3 touches code
- Apply the
bug-analyst's fix plan blindly — verify it against the current code before
implementing, the plan can go stale between posting and implementation
- Auto-close the GitHub issue on a Not Reproducible verdict — leave it open for a human to
triage
- Run more than 2 DoD_BUG fix iterations in Step 3
- Hard-stop on DoR_BUG upfront for a doc auto-created from a raw GitHub issue in this run —
thin Expected/Actual Behavior, Steps to Reproduce, or Severity are expected there; let the
bug-tester fill them from actual investigation instead (see Step 0.4)
- Apply that same leniency to a pre-existing
BUG-XXX doc — a human wrote or reviewed it,
so it's still held to the full DoR_BUG standard immediately in Step 0
Nexa Rules Gate
Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.
Worktree Setup
The fix runs in its own git worktree, so it does not share a working tree with a use case that
is being delivered at the same time.
If the user invoked this skill from the primary checkout, create the worktree first:
git fetch origin main
git worktree add ../$(basename "$PWD")-BUG-XXX -b bug/BUG-XXX origin/main
Run the rest of the pipeline inside that directory. When the fix is green, hand the branch to
/merge-use-case BUG-XXX, which runs the merge gate and removes the worktree.
If a worktree for this bug already exists, reuse it.
Worktree Gate
Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/WORKTREE_GATE.md.
Rollback Checkpoint
Before Step 3 (the only step that writes code), record the current commit:
git rev-parse HEAD
Store as the rollback point for Failure Recovery.
Pipeline
Step 0: Resolve the Bug Doc
- If
$ARGUMENTS matches BUG-XXX, read docs/bugs/BUG-XXX.md directly. Mark this doc
pre-existing and go to 4.
- If
$ARGUMENTS is a GitHub issue URL or bare number, search for an existing bug doc that
already points at it:
grep -rl "<issue-url-or-number>" docs/bugs/
If found, use that BUG-XXX, mark it pre-existing, and go to 4.
- If no bug doc exists for a given GitHub issue, invoke the
report-bug skill (via the Skill
tool, skill: "report-bug") with the issue URL as its argument. This creates the doc and
the thin-pointer issue linkage per its own github-issue origin workflow — do not
duplicate that logic here. Use the resulting BUG-XXX id and mark it auto-created.
- DoR_BUG gate — conditional on origin:
- Pre-existing doc (paths 1–2): a human is presumed to have written or reviewed it, so
hold it to the full standard now. Run
${CLAUDE_PLUGIN_ROOT}/shared/readiness/DEFINITION_OF_READY_BUG.md against it. If any
item fails, report the failures and stop — do not begin the pipeline until the user fixes
the report or explicitly waives the failing items.
- Auto-created doc (path 3): raw GitHub issues are routinely thin or poorly formatted —
missing Expected/Actual Behavior, vague or absent reproduction steps, no severity. Do
not run DoR_BUG here. Proceed straight to Step 1 and let the
bug-tester fill these
gaps from its own investigation instead of demanding a human do it upfront. The gate is
not skipped, only deferred: Step 3 reuses implement/SKILL.md, which runs this exact same
DEFINITION_OF_READY_BUG.md check again before touching code. By then the doc should
carry real, investigated content; if it still doesn't, the pipeline stops there with a
concrete reason instead of a presumptive one now.
- Note the bug doc's GitHub Issue field — this is the issue number every subagent in
this pipeline will comment on. Carry the pre-existing / auto-created marking into
Step 1's prompt.
Step 1: Reproduce (Isolated Agent)
Spawn a typed bug-tester subagent (not general-purpose). The agent's system prompt is
its operating manual — the tester role is loaded as identity, not as a referenced doc. It runs
cold: no visibility into any prior fix attempt or analysis.
Invoke via the Agent tool with subagent_type: "bug-tester". Prompt:
Reproduce the bug described in docs/bugs/BUG-XXX.md (GitHub issue #). This doc is
[pre-existing | auto-created from the raw GitHub issue].
Follow your operating manual (resolve-bug/SKILL.md Step 1, loaded as your identity) to the
letter. If auto-created, fill any missing/placeholder Expected Behavior, Actual Behavior,
Steps to Reproduce, or Severity from your own investigation — do not leave them for a human
to backfill. Report your verdict (Reproducible / Not Reproducible / Insufficient
Information), the evidence you gathered, any fields you filled in, and the issue comment you
posted.
If Insufficient Information (only possible for an auto-created doc — the tester couldn't
determine what to even attempt): stop the pipeline. Print what's missing and:
PIPELINE STOPPED: BUG-XXX — not enough information to reproduce
[tester's report of what's missing]
The raw GitHub issue didn't have enough for the tester to act on. Add the missing detail to
the issue (or docs/bugs/BUG-XXX.md directly) and re-run /resolve-bug.
If Not Reproducible: stop the pipeline here. Print the tester's evidence and:
PIPELINE STOPPED: BUG-XXX not reproducible
[tester's evidence]
The issue has been commented with this finding and left open (Status: Open) for manual
triage — decide whether to close it, request more repro details, or re-run
/resolve-bug BUG-XXX later.
If Reproducible: continue to Step 2.
Step 2: Analyze + Link (Parallel Isolated Agents)
Spawn both subagents in the same message (two Agent tool calls) so they run in parallel —
neither depends on the other's output.
Senior Dev Analyst
Invoke via the Agent tool with subagent_type: "bug-analyst". Prompt:
Analyze the root cause of the bug in docs/bugs/BUG-XXX.md (GitHub issue #), now
confirmed reproducible. Read the tester's reproduction evidence from the issue thread first.
Follow your operating manual (resolve-bug/SKILL.md Step 2, loaded as your identity) to the
letter. You do not edit any file. Report the root cause, the fix plan you posted, and the
issue comment id.
Business Analyst
Invoke via the Agent tool with subagent_type: "requirement-linker". Prompt:
Identify the requirement(s), use case(s), and business rule(s) that the bug in
docs/bugs/BUG-XXX.md (GitHub issue #) violates.
Follow your operating manual (resolve-bug/SKILL.md Step 2, loaded as your identity) to the
letter. You only edit the bug doc's Related Artifacts section — no implementation files.
Report what you linked and the issue comment id.
Wait for both to complete before proceeding.
Step 3: Fix (Main Context)
Read and follow: ${CLAUDE_PLUGIN_ROOT}/skills/implement/SKILL.md for BUG-XXX.
Additionally, before starting implementation, read the bug-analyst's ## Fix Plan comment
from the GitHub issue (gh issue view <number> --comments) and use it as your primary
guidance for root cause and approach. Verify it against the current code rather than
applying it blindly — the analysis was written moments ago but code is the source of truth.
If the plan and the code disagree, trust the code and note the discrepancy in your delivery
summary.
implement/SKILL.md already runs the DEFINITION_OF_READY_BUG.md gate itself before
implementing. For a pre-existing doc this was already satisfied in Step 0 and simply
re-passes. For an auto-created doc, Step 0 deliberately deferred that gate — this is
where it actually bites: if the bug-tester's fill-ins in Step 1 weren't enough to satisfy
DoR_BUG, implement/SKILL.md stops here with the specific failing items, same as it would for
any other BUG-XXX. Resolve those (or have the user waive them) before continuing.
implement/SKILL.md also runs, at its end, its own Post-Implementation Tracking section
(issue comment, status update, close, conventional commit). Do not let that tracking section
run yet — first complete the DoD_BUG gate below, then let it run.
DoD_BUG Gate — after implementation, tests, and build succeed (steps 1–12 of
implement/SKILL.md), read ${CLAUDE_PLUGIN_ROOT}/shared/readiness/DEFINITION_OF_DONE_BUG.md
and check every item against the code and the reproduction steps. Fix any Critical failures
(items that are entirely unmet — e.g. actual behavior still occurs, no regression test added)
and re-check. Up to 2 iterations.
If DoD_BUG still fails after 2 iterations, stop and follow Failure Recovery below — do not
proceed to Post-Implementation Tracking with an unresolved Critical failure.
Once DoD_BUG passes, let implement/SKILL.md's Post-Implementation Tracking section run to
completion (this is what comments "Implemented: ...", sets bug Status to Fixed, closes the
issue if satisfied, and creates the fix(BUG-XXX): ... commit).
Completion
Terminal summary:
## Pipeline Complete: BUG-XXX
| Step | Status |
|--------------------------|--------|
| Reproduce (bug-tester) | Reproducible |
| Analyze (bug-analyst) | Fix plan posted |
| Link (requirement-linker)| [requirements linked] |
| Fix (implement) | ... |
| DoD_BUG | N / 2 |
GitHub issue: <url>
Bug doc: docs/bugs/BUG-XXX.md
Failure Recovery
When the DoD_BUG gate exhausts its 2 iterations without passing:
BUGFIX FAILED: BUG-XXX
[remaining DoD_BUG Critical failures]
Roll back all changes from this pipeline run? (Y/n)
Recommended: Roll back. Resets to the pre-fix state for a clean retry.
Alternative: Keep the code, leave the issue open, and fix the remaining items manually.
Roll back (default)
git reset --hard <saved-commit-hash>
Confirm all pipeline changes have been reverted. Do not let implement/SKILL.md's
Post-Implementation Tracking run — the issue stays open, Status stays whatever it was before
this pipeline started.
Keep code
Leave the working tree as-is and tell the user which DoD_BUG items remain.
