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.
build
Plan-then-execute implementation against SPEC.md with automatic backprop on failure.
caveman
Token-efficient spec encoding for SPEC.md—cuts prose ~75% while preserving precision.
check
Read-only drift detector that diffs SPEC.md against code and reports violations without making changes.
spec
Create and maintain SPEC.md—the single source of truth for project goals, constraints, invariants, and bugs.
cavecrew
Delegate to compressed subagents—investigator, builder, reviewer—to keep main context lean across long sessions.
caveman
Cut token usage ~75% with caveman-mode responses — full technical accuracy, zero fluff