Menu
Fix a robustness bug from GitHub issues using worktrees, test-first development, and subagents.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | bugfix |
| description | Fix a robustness bug from GitHub issues using worktrees, test-first development, and subagents. |
Fix robustness bugs one at a time using isolated worktrees, test-driven development, and parallel subagents.
/bugfix # Pick the next unassigned robustness issue
/bugfix 786 # Fix a specific issue by number
All subagent prompts, scoring heuristics, and keyword maps live in .cursor/skills/bugfix/SUBAGENTS.md. Read that file before spawning any subagent, then pass only the relevant section as the prompt. Do NOT paste SUBAGENTS.md content into the main conversation context.
Check active worktrees first. Run git worktree list and report any existing pathfinder-fix-* worktrees so the user is aware of in-progress or stale fixes.
If no issue number provided, triage and prioritize:
gh issue list --label robustness --state open --json number,title,labels,bodySUBAGENTS.md and score each issue.Fetch the full issue body and comments:
gh issue view <number>
gh issue view <number> --comments
Check for scope mismatch. If the issue is also labeled enhancement, warn the user: "This issue includes new functionality beyond a pure bug fix. The bugfix skill targets minimal fixes — should I proceed with just the bug-fix portion, or hand off to a planning workflow for the full scope?"
Spawn two subagents in parallel. Read SUBAGENTS.md and use the Code investigation (Phase 1a) and Related issues (Phase 1b) prompt templates, filling in the issue details.
Based on the Explore findings, classify the bug:
| Category | Example | Test track |
|---|---|---|
| Logic bug | Wrong calculation, incorrect filtering, bad conditional | Unit test with Jest |
| State bug | Race condition, stale state, incorrect lifecycle | Unit/integration test with Jest + RTL |
| Rendering bug | Wrong component output, missing/duplicate elements | Component test with Jest + RTL |
| UX behavior bug | Navigation broken, tab persistence lost, cross-component failure | Prefer RTL component test; E2E only if component test can't cover it |
| Visual bug | Spinner off-axis, layout shift, styling regression | Structural test track (see below) |
State a root cause hypothesis in one sentence. Present to the user for confirmation. Do NOT write tests until the root cause is agreed upon.
Visual bugs often can't be captured with behavioral assertions, but they usually can be tested structurally. Instead of stopping to ask the user every time:
display: flex and align-items: center", or "element should have class centered-spinner", or "only one .skip-button should exist in the section").Create an isolated worktree:
git worktree add ../pathfinder-fix-<number> -b fix/<number>-<short-slug>
Switch working directory to the worktree for all subsequent work.
Run npm install in the worktree.
This is the most important phase. The test must prove the bug exists before any fix is attempted.
Spawn a Plan subagent. Read the Test design (Phase 4) prompt template from SUBAGENTS.md, fill in the confirmed root cause and Explore findings.
If test strategy calls for E2E (Playwright): check whether the dev server is running (curl -s http://localhost:3000/api/health). If not, tell the user: "This bug needs an E2E test but Grafana isn't running. Please start it with npm run server or I can write a component-level test instead." Prefer component-level RTL tests when they can adequately cover the behavior.
Write the test(s). Follow existing conventions:
foo.test.ts beside foo.ts)src/test-utils/ for shared helpers@testing-library/react and @grafana/data/@grafana/ui as neededit('should not show double skip buttons when ...')Run the tests and confirm they fail for the right reason:
npx jest <test-file> --no-coverage
If the test passes (bug not reproduced), reassess the root cause. Do NOT proceed until you have a failing test.
Commit the test separately:
git add <test-files>
git commit -m "test: add failing test for <short description>
Demonstrates the bug described in #<number>. This test is
expected to fail until the fix is applied in the next commit.
Refs #<number>"
Implement the minimal fix. Hard constraints:
src/validation/architecture.test.ts. Your fix must NOT:
TIER_MAP in src/validation/import-graph.ts)Run the failing test(s) and confirm they now pass:
npx jest <test-file> --no-coverage
npm run check
Commit the fix separately:
git add <fix-files>
git commit -m "fix: <description>
Fixes #<number>"
Record the fix pattern. Append one entry to docs/developer/bugfix-patterns.md (create it if it doesn't exist):
| #<number> | <category> | <root cause pattern — one phrase> | <files touched> | <date> |
If the file is new, add this header first:
# Bugfix patterns
Patterns from resolved robustness issues. Loaded during `/bugfix` Phase 2 to inform classification and root cause hypotheses.
| Issue | Category | Root cause pattern | Files | Date |
| ----- | -------- | ------------------ | ----- | ---- |
Report to the user:
fix/<number>-<slug> in worktree ../pathfinder-fix-<number>Offer next steps:
push — push branch and create a PRnext — start the next highest-priority robustness issuemerge — rebase onto main and merge locally (check for conflicts with other fix branches first)cleanup — remove this worktree (git worktree remove ../pathfinder-fix-<number>)status — list all active fix worktrees and their branchesdocs/developer/bugfix-patterns.md exists and read it. Use prior root cause patterns to inform the current hypothesis.| Subagent | When | Prompt source |
|---|---|---|
Explore (code investigation) | Phase 1 | SUBAGENTS.md → Code investigation |
Explore (related issues) | Phase 1 | SUBAGENTS.md → Related issues |
Plan (test design) | Phase 4 | SUBAGENTS.md → Test design |
Explore (additional paths) | Phase 6 if needed | Ad-hoc, scoped to specific code question |
The full QC8 comment-quality catalog — eight bad comment shapes to delete with before/after examples, plus the keep-list of comments that earn their place. Load before writing or editing code comments, or when a review flags comment quality. AGENTS.md carries the one-line rule and the shape titles; this skill carries the worked examples.
Per-PR documentation-drift prevention. When a PR adds new code subsystems, scripts, skills, docs, plugin routes, feature flags, or changes architecture relationships, this skill produces the AGENTS.md, CLAUDE.md, and .cursor/rules/ updates needed in the same PR so agent guidance never falls behind the code. Use this on /review or directly before merge.
Security audit — frontend (F1-F6 rules from `.cursor/rules/frontend-security.mdc`), Go backend (URL allowlists, token handling, hardcoded secrets, unbounded reads), MCP HTTP transport (size / wallclock / concurrency caps, Zod-validated tool inputs), and dependency audit (`npm audit` high+critical, Go module advisories). Reports findings with concrete remediation per rule. Never edits source — the user applies fixes.
Routed PR review orchestrator. Load for `/review` command or any PR review task.
Generate a structured PR description from the current diff using `docs/design/CONCERNS.md` routing. Interviews the author for motivation before drafting. Produces canonical sections (Summary, What to look at, Why, How to verify, Breaking changes, Reversibility) tailored to change type. Outputs the draft for human review; can apply via `gh pr edit` after explicit confirmation. Pair with `/review` — this skill drafts, `/review` reviews.
Locate technical debt in a subsystem or architectural component of a codebase. Use when the user runs `/techdebt <subsystem>` or asks to audit a module for smells, duplication, prop drilling, dead code, or other debt patterns. Examples: "/techdebt src/auth", "find tech debt in components/docs-panel", "audit the interactive-engine for smells".