pipeline-bugfix
Bug fix pipeline — investigate root cause, apply fix with scope lock, critique, QA verification, ship. Chains investigate, guard, verification, critique skills, qa-only, and ship into a disciplined fi
SKILL.mdskills/pipeline-bugfix/SKILL.md
GitHubPipeline: Bug Fix
You are orchestrating a bug fix pipeline. The iron law: no fix without root cause. Execute each stage sequentially.
Pipeline State
Create a pipeline tracker at .gstack/pipeline-bugfix-{date}.md at the start.
## Pipeline: Bug Fix
Started: {timestamp}
Bug: {description}
| # | Stage | Status | Gate | Duration | Notes |
|---|-------|--------|------|----------|-------|
| 1 | INVESTIGATE | pending | — | — | — |
| 2 | FIX | pending | — | — | — |
| 3 | CRITIQUE | pending | — | — | — |
| 4 | QA | pending | — | — | — |
| 5 | SHIP | pending | — | — | — |
Stage 1: INVESTIGATE
Invoke /investigate with the bug description, error message, or reproduction steps.
The investigate skill enforces:
- Root cause identification before any fix
- 3-strike rule: 3 failed hypotheses → STOP and escalate
- PreToolUse hooks lock the debug scope via
/freeze
Gate: Root cause must be identified. A DEBUG REPORT must be produced with:
- Symptom (what the user observed)
- Root cause (what was actually wrong)
- Proposed fix (what needs to change)
On pass: Update tracker row 1 → PASS, extract the root cause and proposed fix for Stage 2. On fail: If 3 strikes hit → update tracker row 1 → BLOCKED, report to user with findings so far.
Stage 2: FIX
2a: Scope lock
Identify the directory containing the affected files. Invoke /guard {directory} to activate:
- Edit/Write boundary lock (freeze)
- Destructive command interception (careful)
2b: Apply the fix
Implement the fix identified in Stage 1. Write a regression test that:
- Fails WITHOUT the fix (red)
- Passes WITH the fix (green)
2c: Verify
Apply the CLAUDE.md evidence gate (Verification Before Done) — never claim fixed without fresh evidence produced this session:
- Run the regression test → must pass
- Run the full test suite → must pass
- Demonstrate the fix with evidence (command output, not assertions)
Gate: Regression test passes the red-green cycle. Full test suite passes.
On pass: Update tracker row 2 → PASS, proceed to Stage 3. On fail: If tests fail, investigate further. Do NOT proceed with a broken test suite.
Stage 3: CRITIQUE
Detect which critique applies based on the files changed by the fix:
git diff main...HEAD --name-only
| Changed files | Critique skill |
|---|---|
| Backend/API/server files | /backend-critique |
| Auth, secrets, crypto, user data | /security-critique |
| UI/frontend files | /design-critique |
| Infra/CI/deploy files | /operations-critique |
Run the most relevant critique (one is usually enough for a bugfix). If files span multiple domains, run the top 2 as parallel subagents.
Gate: Critique grade B or above.
If grade C or below:
- Report findings
- Fix the issues raised (they're usually small for a bugfix)
- Re-run critique to confirm B+
On pass: Update tracker row 3 → PASS (include grade), proceed to Stage 4. On skip: If the fix is < 5 lines and touches only one file, skip critique (update tracker → SKIPPED). This override must be noted.
Stage 4: QA
Invoke /qa-only (report-only mode — no additional fixes at this stage).
If the project has a running dev server, use it. Otherwise start one.
The QA skill runs browser testing and produces a health score. Since this is a bugfix, focus on:
- The specific area where the bug was found (regression check)
- Adjacent features that could be affected
- Overall health score
Gate: Health score >= 70. No NEW issues introduced (compare against baseline if available).
On pass: Update tracker row 4 → PASS (include health score). On fail: If new issues found, they were likely introduced by the fix. Go back to Stage 2, refine the fix.
Stage 5: SHIP
Invoke /ship.
For bugfixes, the ship skill should produce:
- A commit message starting with
fix:orfix(scope): - A PR with the DEBUG REPORT from Stage 1 included in the description
- The regression test included in the PR
Gate: PR created. Tests pass.
On pass: Update tracker row 5 → PASS (include PR URL).
Final Report
## Pipeline Report: Bug Fix
Bug: {description}
Root Cause: {root cause from Stage 1}
Fix: {summary of changes}
Run: {timestamp}
Duration: {total elapsed}
| # | Stage | Skill(s) | Result | Gate | Duration |
|---|-------|----------|--------|------|----------|
| 1 | INVESTIGATE | investigate | {result} | Root cause: {found/blocked} | {time} |
| 2 | FIX | guard, verification | {result} | Red-green: {pass/fail} | {time} |
| 3 | CRITIQUE | {critique skill} | {result} | Grade: {letter} | {time} |
| 4 | QA | qa-only | {result} | Score: {N}/100 | {time} |
| 5 | SHIP | ship | {result} | {PR URL} | {time} |
Overall: {PASS / BLOCKED}
Regression test: {file path}