backprop
juliusbrussee/cavekit
Trace bugs to root cause and edit specs to prevent recurrence.
What is backprop?
Backprop is a bug-to-spec protocol that goes beyond fixing code: when a test fails or bug is reported, you trace the root cause, decide if a new invariant (§V) would catch it, and append to the spec's bug log (§B). This prevents the same class of bug from recurring.
- Trace failure output or bug reports to exact file:line and root cause
- Analyze whether a new spec invariant (§V) would catch the bug class
- Propose spec changes with §B (bug log) and §V (invariant) entries
- Generate failing tests that validate new invariants before fixing code
- Verify fixes pass new tests and don't regress the full suite
- Log all changes in a single commit linking spec edits to code fixes
How to install backprop
npx skills add https://github.com/juliusbrussee/cavekit --skill backprop- A SPEC.md file with §B (bug log), §V (invariants), §I (interface), and §T (target) sections
- A test suite that can be run to verify fixes
- Git for committing spec + test + code changes together
How to use backprop
- 1.Read the failure output or bug report and locate the exact file:line of wrong behavior
- 2.Name the root cause in one clear sentence
- 3.Ask: would a new §V invariant catch this bug class? Is §I or §T wrong instead?
- 4.Draft the spec change: add a §B row with date and root cause, add a §V line with a testable rule
- 5.Write a failing test that validates the new invariant (e.g., TestV7_RefundIdempotent)
- 6.Fix the code and run the new test until it passes; run full suite to check for regressions
- 7.Commit spec edit + test + code fix together with message: backprop §B.<n> + §V.<N>: <one-line cause>
Use cases
- Test fails at build verification: trace the failure, add invariant to prevent recurrence
- User reports production bug: backprop to spec so the same failure mode is caught by future tests
- Post-mortem after incident: formalize the root cause as a testable invariant in the spec
- Spec violation flagged by /check: use backprop to decide if §V, §I, or §T needs updating
- Recurring bug pattern: search §B history to find precedent and strengthen the invariant
- Developers using Specification-Driven Development (SDD) workflows
- Teams that want specs to evolve with bug fixes, not just code
- Engineers doing post-mortems who need to formalize lessons learned
- Anyone building systems where preventing bug recurrence is critical
backprop FAQ
Backprop when a test fails at /build, a user reports a bug, after a production incident post-mortem, or when /check flags a VIOLATE with root cause found.
Still append a §B entry to record that this failure mode was considered, but skip the §V invariant. Future bugs with the same smell can search §B and find the precedent.
A good invariant is testable in code (grep-able or assert-able), scoped to a behavior not a file, stated positively when possible, and references §I surface where it applies. Avoid vague rules like 'code should be correct.'
Yes. A new invariant without a test is a lie. Write the failing test first, then fix the code to make it pass.
Skip the §V invariant and upgrade the dependency instead, noting the change in §C. Still add a §B entry to record the failure mode.
Full instructions (SKILL.md)
Source of truth, from juliusbrussee/cavekit.
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
/buildverification. - User reports bug.
- Post-mortem after production incident.
/checkflags 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 (
! holdover⊥ 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++vsi--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:
- §B entry (always).
- §V entry (usually).
- Test file (when §V added).
- Code fix.
- One commit.
No dashboards. No log files. SPEC.md + git is the full history.
Related skills
More from juliusbrussee/cavekit and the wider catalog.
