| name | fix-bug |
| description | Use when fixing a bug, crash, regression, broken endpoint, or any reported wrong behavior — orchestrates the full chain investigate (root cause) → reproducer test → minimal fix → review → verify. Triggers on phrases like "fix bug", "fix the issue", "почини баг", "сломалось", or the /fix-bug slash command. |
Bug Fix Chain
End-to-end orchestration for bug fixes. Surgical changes only — every changed line must trace to the bug. Discipline is enforced by checkpoints; do not skip a phase.
Core principle (Karpathy): investigate → reproduce → minimal fix → verify. No "while I'm here" refactors. No improvements to adjacent code, comments, or formatting. Match existing style even if you would do it differently.
Mandatory background reads
If not already in this session:
- Root
CLAUDE.md — project context, especially Known Gotchas (recurring footguns)
- Relevant files in
.claude/rules/ depending on the bug area (integration-tests.md, messaging-tests.md, db-migrations.md, etc.)
board-tracking.md — issue lifecycle for the work- Per-module / per-service
CLAUDE.md for the affected area
TodoWrite scaffold
Open the chain by writing this todo list. Mark cancelled phases as cancelled, never silently skip.
- Phase 0 — Issue tracking (find or create as
type::bug, move to In Progress)
- Phase 1 — Investigate (gather evidence, form hypothesis)
- Phase 2 — Reproducer test (failing test that captures the bug)
- Phase 3 — Plan minimal fix
- Phase 4 — Implement fix
- Phase 5 — Re-run reproducer + all tests
- Phase 6 — Code review (code-reviewer)
- Phase 7 — Security review (if auth / SQL / permission related)
- Phase 8 — Verify (build + manual smoke if UI bug)
- Phase 9 — Add observability / log point if symptom was non-obvious
- Phase 10 — Close issue / link PR
Phase 0 — Issue tracking
Per board-tracking.md:
- Search existing issues by symptom keywords. Reuse if found.
- If none — create with
type::bug, source::user (if user reported) or source::agent (if agent spotted), priority default medium (high if blocks prod / auth / payment / data loss). Description includes symptom + repro steps + suspect file:line if known.
- Move to
In Progress (replace status label).
- Note iid for commit messages
fix(svc): bar (#N) and PR Closes #N.
Skip Phase 0 only for one-line copy / typo / styling fixes (mark cancelled with reason).
Phase 1 — Investigate
ALWAYS use the investigate-and-fix skill OR superpowers:systematic-debugging. They define the platform-specific evidence-gathering toolkit. Do not skip — guessing the cause and editing wastes more time than 5 minutes of investigation.
For prod bugs: read logs from your observability stack (Loki / CloudWatch / Datadog) first. For local bugs: container logs and local observability if up. SSH to prod is allowed if user policy permits.
For test failures: debugger subagent. For non-trivial bugs that span multiple services: Explore subagent for parallel read-only investigation.
Output of Phase 1 (write into Phase 2 todo):
- Symptom (exact error / wrong output)
- Reproduction steps
- Suspected root cause (one hypothesis, not three)
- Affected files / endpoints / handlers (absolute paths)
- Bug class: backend / frontend / migration / data / config
If 2+ hypotheses fail in a row — STOP and re-examine assumptions before continuing. The bug is somewhere you have not looked.
Phase 2 — Reproducer test
TDD discipline (superpowers:test-driven-development). Write the test BEFORE the fix.
Backend:
- Integration test in the affected service's test project
- Test must fail on current code (run it once, observe the failure)
- Use
integration-test-coverage skill to get the right harness
- For event publishing bugs: L2 test that tracks outbox publishes — exactly what catches "publish without flush" bugs
- For event handler bugs: L1 test with in-process invoke
Frontend:
- Unit test (Vitest / Jest) if pure logic
- Playwright golden-path interaction if UI / browser-only bug
Migration / schema bug:
- Reproducer is a fresh DB run: tear down + bring up + run migrations and check the symptom returns
- If migration was already deployed and column was dropped — restore from backups
Exception: pure copy / styling fix may not need a test. Mark Phase 2 cancelled with reason "trivial visual fix, manually verified in Phase 8".
Commit the failing test before writing the fix — this proves the test is real. (Optional but encouraged.)
Phase 3 — Plan minimal fix
State in plain words:
- What ONE thing changes
- Why it fixes the symptom
- What stays untouched
Refuse temptation:
- Do NOT clean up adjacent code, comments, naming, formatting.
- Do NOT refactor things that are not broken.
- Do NOT widen the scope ("while I'm here, let me also...").
- If you notice unrelated dead code or other bugs, mention them in the final report — do NOT delete or fix them in this chain.
The test: every changed line should be answerable to "this is here to fix the reported bug."
Phase 4 — Implement fix
Follow project conventions from CLAUDE.md / .claude/rules/. Common rules (still applicable for fixes):
- Result/Error monad — never
throw for business errors
- Time-ordered UUIDs in production code
- Outbox publish always followed by SaveChanges / commit (see
messaging-tests.md)
- Trailing slashes on routes if gateway requires it
- New migration only — never edit existing (see
db-migrations.md). Drop/rename column may require container rebuild on prod, not just restart.
If the fix orphans imports / variables / functions — remove only those orphans. Do NOT remove pre-existing dead code.
Phase 5 — Re-run tests
If the reproducer passes but other tests now fail → the fix is too wide. Return to Phase 3, narrow the change.
Phase 6 — Code review
code-reviewer subagent on the changed files. Pass the file list explicitly. Reviewer checks:
- Surgical scope (no unrelated edits)
- Patterns followed (Result/Error, layer boundaries, outbox flush)
- Regression test exists and is meaningful
For a fix to a single service with non-trivial domain logic: use review-service skill (full audit) instead of code-reviewer.
Address every blocker.
Phase 7 — Security review
Invoke security-reviewer if the bug or fix touches:
- Authentication, token handling, refresh / sign-in cookies
- Authorization — permissions, roles, ownership checks, entitlement checks
- Raw SQL or untyped ORM query (SQL injection class)
- Anonymous endpoints or widened
AllowAnonymous
- File upload validation, signed URLs
- Cross-service contract auth headers
If the bug was an entitlement / IDOR class issue — re-run the content-access skill checklist independently of security-reviewer.
Phase 8 — Verification
Invoke superpowers:verification-before-completion. Use full-dev-verification skill or run piecewise:
If reproducer was skipped (trivial visual fix), the browser check is the only proof the bug is gone — do not skip it.
Phase 9 — Observability
If the symptom was hard to find from existing logs / traces, add ONE log point at the suspect spot so the next regression is faster to diagnose. Use structured logging properties. Do not add generic "method called" logs.
If the bug exposed a class of issues (e.g. missing outbox flush, missing entitlement check), consider whether the relevant CLAUDE.md "Known Gotchas" section should grow a new bullet. Do NOT add the gotcha unless you are sure it is reusable knowledge.
Phase 10 — Close issue / link PR
- PR open → ensure description has
Closes #N. Move issue to In Review.
- Direct commit to default branch → close manually + add note with commit SHA.
- If during fix you found additional unrelated bugs — separate issues for each (
source::agent, Backlog), do not bundle. The current issue closes only if the originally-reported symptom is gone.
Final report
Caveman mode (terse, Russian if user used Russian):
- Root cause, one sentence
- Files changed (absolute paths)
- Reproducer test name + path
- Verification results (which boxes green)
- Any unrelated issues spotted (mention only — do not silently fix; never revert / fix unrelated code without explicit ask)
