# Resolve Bug > 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. - Skill: `nexadevapp/resolve-bug` (Agent Skill) - Install (CLI): `npx skillmds@latest add nexadevapp/resolve-bug` - Raw SKILL.md: https://api.skillmd.com/api/skills/nexadevapp/resolve-bug/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: nexadevapp (https://skillmd.com/u/nexadevapp) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/nexadevapp/resolve-bug --- # 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: ```bash 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 1. If `$ARGUMENTS` matches `BUG-XXX`, read `docs/bugs/BUG-XXX.md` directly. Mark this doc **pre-existing** and go to 4. 2. If `$ARGUMENTS` is a GitHub issue URL or bare number, search for an existing bug doc that already points at it: ``` grep -rl "" docs/bugs/ ``` If found, use that `BUG-XXX`, mark it **pre-existing**, and go to 4. 3. 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**. 4. **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. 5. 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: "nexa-claude-go: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: "nexa-claude-go: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: "nexa-claude-go: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 --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: 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 ``` 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.