| name | bugfix-quick |
| description | Fast bug fixes with root cause investigation + TDD. Enforces 'no fix without root cause' discipline and verification protocol. Without this skill, fixes are applied at symptoms instead of sources, and bugs return. |
| autoInvoke | true |
| priority | medium |
| triggers | ["fix bug","broken","crash","not working"] |
| allowed-tools | Read, Grep, Glob, Edit, Write, Bash |
| effort | low |
| user-invocable | false |
AI-consumed reference. Optimized for Claude to read during execution.
Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md
or docs/getting-started/ depending on topic.
Quick Bugfix
For bugs only. Features/refactors → run-orchestrator.
Core Principle
NO FIXES WITHOUT ROOT CAUSE. Fix at SOURCE, not symptom.
Process (4 Steps)
| Step | Name | Agent | Statusline |
|---|
| S1 | Investigate | lead (inline) — uses Read/Grep/Bash to reproduce | bugfix S1 |
| S2 | Test RED | tester — writes failing test | bugfix S2 |
| S3 | Fix GREEN | architect / frontend / mobile (per artifact, via agent-detector) | bugfix S3 |
| S4 | Verify | tester — runs full suite | bugfix S4 |
Announce per step. When transitioning, surface to the user: ─── Step S{N} · {Name} ─── Dispatching {agent}…. Also update run-state.json#current_step (one of: investigate, test-red, fix-green, verify) and #active_agent so the statusline reflects reality.
1. Investigate
- Read error + stack trace
- Reproduce the bug
git log / git diff for recent changes- Trace backward: where did bad data originate?
- Context economy (
rules/core/context-economy.md) — Grep for the failing symbol first, then Read with offset+limit on the matched lines only. Don't read the full file unless the bug spans it.
2. Write Failing Test (RED)
- Test that reproduces the bug exactly
- Pick the right layer (
skills/test-writer/SKILL.md#test-type-selection). If the bug is a UI / user-flow / auth / payment regression → e2e spec via Playwright MCP, not a unit test that won't actually reproduce it. If the bug is in pure logic → unit. The test must fail for the right reason.
- User confirms test FAILS
3. Fix (GREEN)
- Minimal, focused change at root cause
- User confirms test PASSES
4. Verify
- Run full test suite — and the e2e suite if S2 wrote an e2e spec (
npx playwright test / npx cypress run). No regressions in either.
- Read output, THEN claim result. "Tests passed" with no pass count =
0 tests collected = bug.
- Wrong: "Should work now" / Right: "Tests pass: [output]"
Red Flags (Return to Step 1)
"Quick fix for now" / "Just try changing X" / "It's probably X" / "Seems fixed"
Output
## Bug Fix: [Description]
**Root Cause:** [Why — traced to source]
**Test Added:** [file + test name]
**Fix Applied:** [file + change summary]
**Verification:** Tests pass, no regressions
If complex → switch to run-orchestrator.
Escalation: If the bug resists quick fix (intermittent, race condition, "works on my machine", multiple plausible causes), escalate to skills/deep-debugging/SKILL.md for scientific-method root-cause analysis.
Related Rules
rules/core/tdd-workflow.md — Failing test before fixrules/core/verification.md — Run tests, read output, then claimrules/core/execution-rules.md — Root-cause disciplinerules/core/simplicity-over-complexity.md — Minimal fix at root cause, no speculative refactoring during bug fix
