The /to-fix Skill
Treats defects as mathematical theorems to prove. Rejects blind guessing and shotgun patches, isolates broken seams via bisection search, and enforces failing reproduction tests before fixing.
"If you cannot solve the proposed problem, try to solve first some related problem. Could you imagine a more accessible related problem? An analogous problem? An auxiliary problem?" — George Pólya, How to Solve It (1945)
/to-fix Diagnose uncaught null pointer in checkout payment webhook and generate bug remediation plan.What it does
to-fix treats defects as mathematical theorems to prove. It refuses blind guessing, speculative trial edits, or shotgun patching. Grounded in First Principles reasoning, it classifies failures into 1 of 5 root-cause categories (Syntax/Type mismatch, Contract/Serialization drift, State/Async concurrency race, Environment/Dependency skew, or Domain Logic violation) and isolates the broken Clean Architecture seam using systematic $O(\log n)$ bisection search.
It applies the **Prove-It Pattern**: it specifies or authors an automated reproduction test that fails for the exact reason (TDD Red) to serve as immutable proof before designing a fix. It enforces the Caller Grep Mandate (fixing root contracts rather than individual callers) and compiles a phased Bug Remediation Plan in docs/bug-reports/{slug}-bugfix.md. It refuses to modify production code directly during diagnosis, handing off approved remediation plans to /to-code.
When to reach for it
Where the work currently lives decides whether this is the right skill:
| The work is… | Reach for |
|---|---|
| An unexpected defect, crash trace, or broken runtime invariant | /to-fix (isolate root cause and formulate reproduction test) |
| A defect in a shared utility or port adapter consumed across multiple call sites | /to-fix (enforces Caller Grep Mandate to fix root contract) |
| A routine typo, localized null-check, or config tweak (≤ 2 files) | /to-quick-fix |
| An approved bug remediation plan ready to be implemented | /to-code @docs/bug-reports/{slug}-bugfix.md |
| A defect rooted in fundamentally broken architecture or specifications | /to-spec (architectural redesign) |
Prerequisites
- Reproduction Telemetry: Crash logs, stack traces, expected vs. actual behavior, or failing payloads.
- Working Tree Hygiene: Inspects
git statusandgit difffirst to verify if uncommitted local edits introduced the regression. - No Direct Production Editing: Diagnostic actions are strictly confined to seam analysis, reproduction tests, and authoring
docs/bug-reports/{slug}-bugfix.md.
What one run does
A single first-principles bug remediation run follows seven analytical steps:
- Working Tree Hygiene & Recent Diff Check: Inspects uncommitted edits and recent commits (
git log -n 5) to establish if a localized commit recently introduced the regression. - Root-Cause Category Classification: Classifies defect into 1 of 5 failure categories (Syntax, Contract, State/Concurrency, Environment, Domain Logic).
- First-Principles Seam Tracing & Caller Grep: Traces data flow from ingress trigger to failure point. Greps for all callers of shared functions: fixes the root defect once in the shared seam rather than patching one symptom caller.
- Systematic Bisection Search: Halves middleware chains, payload configs, or commit histories (
git bisect) to locate exact failure seams ($O(\log n)$ isolation). - The "Prove-It" Pattern (Reproduction Test): Authors an automated reproduction test that fails for the exact, expected reason (TDD Red). Serves as immutable proof that the bug exists.
- 3-Strike Incubation Circuit-Breaker: If 2–3 consecutive diagnostic hypotheses fail reproduction, halts immediately, cleans scratch harnesses, and authors a structured Contradiction / Dilemma Report.
- Remediation Plan Generation & Handoff: Authors formal plan at
docs/bug-reports/{slug}-bugfix.mdwith reproduction test ticket, surgical fix ticket, and rollback strategy. Hands off to/to-code.
Common questions
Why can't the agent just quickly patch the bug directly in the source file?
Shotgun patching without a failing reproduction test leaves you unable to prove the bug actually existed or prevent its regression. Writing the reproduction test (TDD Red) first guarantees that the bug is mathematically isolated and permanently sealed.
What is the 3-Strike Incubation Circuit-Breaker?
If 2–3 consecutive diagnostic hypotheses fail to reproduce the defect, stacking further guesses will only pollute the working tree. The agent halts immediately, cleans scratch harnesses, and presents a Contradiction Report in chat.
What is the Caller Grep Mandate?
When a shared helper returns null or throws, adding a null-check inside one caller leaves every sibling caller vulnerable to the exact same crash. Grepping all callers allows fixing the contract once at the root seam.
It's working if
- It classifies the defect into one of the 5 mathematical failure categories before theorizing.
- It greps all callers of shared functions before designing a fix.
- It authors a targeted automated reproduction test that fails for the exact reason (TDD Red).
- It respects the 3-Strike Circuit Breaker if hypotheses fail reproduction.
- It writes zero production code during diagnosis, authoring
docs/bug-reports/{slug}-bugfix.md.
Where it fits
to-fix is Phase 5 in the main idea-to-ship pipeline:
/to-explore → /to-prd → /to-spec → /to-clarify → /to-plan → 🛑 PAUSE → /to-code → /to-review ──(defects)──▶ 🩺 /to-fix → /to-docs
It is invoked when defects or broken invariants are identified during testing or review. Once the root cause is isolated and docs/bug-reports/{slug}-bugfix.md is approved, it hands off to /to-code for implementation.