resolve-bug
/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.
- Author
- nexadevapp ↗
- Repository
- nexa-claude-skills-marketplace ↗
- Licence
- Apache-2.0
- Last repository change
- 25.09.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 25.09.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
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.
Triggers from the description
Original author 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.
How it works
- Instructions
- Prerequisites
- DO NOT
- Nexa Rules Gate
- Worktree Setup
- Worktree Gate
- Rollback Checkpoint
- Pipeline
- Completion
- Failure Recovery
SKILL.md preview
---
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:
```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 "<issue-url-or-number>" 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 #<number>). 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 #<number>), 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 #<number>) 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.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · nexadevapp/nexa-claude-skills-marketplace | 100 | Apache-2.0 |
| nexadevapp/nexa-claude-skills-marketplace | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 49adebdf74d8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100bugfix-workflow
End-to-end bugfix workflow. Test first, plan, fix, verify. Use when the user says "fix bug", "bugfix", "investigate issue", "fix #NNN", or any bug-related work. Covers reproduction, test creation, RCA, fix implementation, verification, and ticket documentation. - 100implementing-bug-fix
Implements a bug fix from a GitHub issue URL or ID, or auto-selects the next feasible confirmed P0-P3 bug. Researches and reproduces the bug, plans, implements, tests, and creates a merge-ready PR. Use when asked to fix a bug, implement a bugfix, or run /implementing-bug-fix. - 100fix-issue
Analyze and fix a GitHub issue for the iam-policy-validator project. Use when the user wants to fix a GitHub issue, resolve a bug report, or implement a feature request from an issue. Triggers on "/fix-issue", "fix issue #42", "resolve this GitHub issue", or "work on issue". - 100bugfix
Fix a bug from a GitHub issue, following the reproduce-first workflow. Use when the user asks to fix a bug, investigate a GitHub issue, or debug a user-reported problem. Takes a GitHub issue URL or number as input. - 100resolve-issue
Takes ONE issue (bug report, feature request, tracker issue #N, a pasted screenshot of a defect) to a VERIFIED BRANCH through a ranked diagnosis, spec, plan, parallel build with an adversarial verifier per task, gates and docs, then stops for a human yes before anything is… - 100bugfix-workflow
Use when the user says "fix bug", "fix #NNN", or you hit a failing test or reproducible defect that needs fixing end-to-end (not investigation alone). The full bugfix workflow from reproduction through a verified, documented fix.