backprop — Claude Code skill: what it does, how to install
Turns bug fixes into specification updates in SPEC.md. The agent traces the failure, drafts a testable invariant, adds a failing test, and commits everything together.
npx skills add JuliusBrussee/cavekit --skill backprop -a claude-codeWhat backprop does
Plan-then-execute workflows fix broken code and move on. The backprop protocol ties every defect back to SPEC.md so the same bug class cannot recur. It triggers automatically when /build tests fail, when a user reports a problem, during an incident post-mortem, or when /check flags a VIOLATE state.
Execution follows six steps. The agent traces the exact line of failure and states the root cause in one sentence. Next, it evaluates whether a new §V invariant is required and logs the issue in the §B section. It writes a failing test named after the invariant before touching any implementation files. Once tests pass, the spec edit, test, and code fix merge into a single git commit.
Not every issue earns a new invariant. Purely mechanical typos, one-time migrations, and external dependency failures bypass §V creation, though the §B log entry remains mandatory. The protocol uses no separate dashboards or log files. Your SPEC.md file and git log serve as the entire source of truth.
What it helps with
- stop bug recurrence by adding testable invariants to
SPEC.md - document the root cause in the specification §B table
- generate a failing test before writing the code fix
- bundle specification changes, tests, and code fixes into a single commit
Example prompts for the agent
- Tests failed during /build verification, run backprop to trace the root cause and update SPEC.md
- A user reported duplicate charges on retry, execute backprop to add a §V invariant and a test
- Trace this production incident and log the failure mode to §B using backprop
How to install backprop
1Skills CLI (Vercel)
npx skills add JuliusBrussee/cavekit --skill backprop -a claude-code2Manually: put the files in place
~/.claude/skills/backprop/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/backprop/
1Skills CLI (Vercel)
npx skills add JuliusBrussee/cavekit --skill backprop -a codex2Manually: put the files in place
.agents/skills/backprop/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add JuliusBrussee/cavekit --skill backprop -a cursor2Manually: put the files in place
.cursor/skills/backprop/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install JuliusBrussee/cavekit backprop2Manually: put the files in place
.github/skills/backprop/SKILL.md1Skills CLI (Vercel)
npx skills add JuliusBrussee/cavekit --skill backprop -a gemini-cli2Platform CLI
gemini skills install https://github.com/JuliusBrussee/cavekit --path skills/backpropManually: put the files in place
.devin/skills/backprop/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add JuliusBrussee/cavekit --skill backprop -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about backprop
How do I install backprop in Claude Code?
Run npx skills add JuliusBrussee/cavekit --skill backprop -a claude-code. The skill will be placed into ~/.claude/skills/backprop/SKILL.md.
What does the backprop skill do?
It guides the assistant through a bug-to-spec workflow. The agent identifies the failure cause, updates the §B log in SPEC.md, formulates an invariant §V, writes a regression test, and commits the result.
When should a §V invariant be skipped?
Skip adding a §V invariant when the bug is an isolated typo, a one-off migration, or an external dependency issue. Even in those cases, the agent still records a §B entry.
Source text
SKILL.md · MIT
--- name: backprop description: | Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask. --- # backprop — bug → spec Plan-then-execute fixes the code & forgets. SDD fixes the code AND edits spec so recurrence is impossible. That edit is backprop. ## WHEN TO BACKPROP - Test failed at `/build` verification. - User reports bug. - Post-mortem after production incident. - `/check` flags VIOLATE with root cause found. ## SIX STEPS ### 1. TRACE Read failure output / bug report. Find exact file:line of wrong behavior. Name root cause in one caveman sentence. ### 2. ANALYZE Ask three questions: - Would a new §V invariant catch this class of bug? (most common: yes) - Is §I wrong — did spec claim shape the code cannot deliver? (sometimes) - Is §T wrong — did we build the wrong thing? (rare but real) ### 3. PROPOSE Draft the spec change. Never skip §B; §V/§I/§T are case-by-case. Template: ``` §B row: B<next>|<date>|<root cause>|V<N> §V line: V<next>: <testable rule that would have caught it> ``` Example: ``` §B row: B3|2026-04-20|refund job ran twice on retry|V7 §V line: V7: ∀ refund → idempotency key check before charge reversal ``` ### 4. GENERATE TEST New invariant without test = lie. Add failing test first. Name test so it cites the invariant: `TestV7_RefundIdempotent`. ### 5. VERIFY Fix code. Run test. Must pass. Run full suite. Must not regress. ### 6. LOG Commit spec edit + test + code fix together. Commit msg: `backprop §B.<n> + §V.<N>: <one-line cause>`. ## WHAT MAKES A GOOD INVARIANT - Testable in code (grep-able or assert-able). - Scoped to a behavior, not a file. - Stated positively when possible (`! hold` over `⊥ forbid`). - References §I surface where it applies. **Bad**: V8: code should be correct. **Good**: V8: ∀ pg_query ! params interpolated via driver, ⊥ string concat. ## WHEN NOT TO ADD §V - Bug was purely mechanical typo with no class (`i++` vs `i--` in throwaway). - Fix is a one-time migration. - Root cause is external dep (upgrade deps instead, note in §C). Still append §B entry — record that this failure mode was considered. Future bug with same smell → §B search shows precedent. ## OUTPUT SHAPE Every backprop run produces: 1. §B entry (always). 2. §V entry (usually). 3. Test file (when §V added). 4. Code fix. 5. One commit. No dashboards. No log files. SPEC.md + git is the full history.
© JuliusBrussee · MIT · JuliusBrussee/cavekit
