backprop

Name: backprop
Author: JuliusBrussee

2.3kinstalls81forks

How to install backprop?

juliusbrussee/cavekit/backprop

$npx -y skills add JuliusBrussee/cavekit --skill backprop

Installs into the current project.

Summary

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 expl

Files · 1

View on GitHub

SKILL.md

1	# backprop — bug → spec
2
3	Plan-then-execute fixes the code & forgets.
4	SDD fixes the code AND edits spec so recurrence is impossible.
5	That edit is backprop.
6
7	## WHEN TO BACKPROP
8
9	- Test failed at `/build` verification.
10	- User reports bug.
11	- Post-mortem after production incident.
12	- `/check` flags VIOLATE with root cause found.
13
14	## SIX STEPS
15
16	### 1. TRACE
17	Read failure output / bug report.
18	Find exact file:line of wrong behavior.
19	Name root cause in one caveman sentence.
20
21	### 2. ANALYZE
22	Ask three questions:
23	- Would a new §V invariant catch this class of bug? (most common: yes)
24	- Is §I wrong — did spec claim shape the code cannot deliver? (sometimes)
25	- Is §T wrong — did we build the wrong thing? (rare but real)
26
27	### 3. PROPOSE
28	Draft the spec change. Never skip §B; §V/§I/§T are case-by-case.
29
30	Template:
31	```
32	§B row: B<next>\|<date>\|<root cause>\|V<N>
33	§V line: V<next>: <testable rule that would have caught it>
34	```
35
36	Example:
37	```
38	§B row: B3\|2026-04-20\|refund job ran twice on retry\|V7
39	§V line: V7: ∀ refund → idempotency key check before charge reversal
40	```
41
42	### 4. GENERATE TEST
43	New invariant without test = lie. Add failing test first.
44	Name test so it cites the invariant: `TestV7_RefundIdempotent`.
45
46	### 5. VERIFY
47	Fix code. Run test. Must pass. Run full suite. Must not regress.
48
49	### 6. LOG
50	Commit spec edit + test + code fix together.
51	Commit msg: `backprop §B.<n> + §V.<N>: <one-line cause>`.
52
53	## WHAT MAKES A GOOD INVARIANT
54
55	- Testable in code (grep-able or assert-able).
56	- Scoped to a behavior, not a file.
57	- Stated positively when possible (`! hold` over `⊥ forbid`).
58	- References §I surface where it applies.
59
60	Bad: V8: code should be correct.
61	Good: V8: ∀ pg_query ! params interpolated via driver, ⊥ string concat.
62
63	## WHEN NOT TO ADD §V
64
65	- Bug was purely mechanical typo with no class (`i++` vs `i--` in throwaway).
66	- Fix is a one-time migration.
67	- Root cause is external dep (upgrade deps instead, note in §C).
68
69	Still append §B entry — record that this failure mode was considered. Future bug with same smell → §B search shows precedent.
70
71	## OUTPUT SHAPE
72
73	Every backprop run produces:
74	1. §B entry (always).
75	2. §V entry (usually).
76	3. Test file (when §V added).
77	4. Code fix.
78	5. One commit.
79
80	No dashboards. No log files. SPEC.md + git is the full history.

People who liked this also viewed

6 picks

Type

backprop

2.3kinstalls81forks

View on GitHub

How to install backprop?

juliusbrussee/cavekit/backprop

$npx -y skills add JuliusBrussee/cavekit --skill backprop

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# backprop — bug → spec
2
3	Plan-then-execute fixes the code & forgets.
4	SDD fixes the code AND edits spec so recurrence is impossible.
5	That edit is backprop.
6
7	## WHEN TO BACKPROP
8
9	- Test failed at `/build` verification.
10	- User reports bug.
11	- Post-mortem after production incident.
12	- `/check` flags VIOLATE with root cause found.
13
14	## SIX STEPS
15
16	### 1. TRACE
17	Read failure output / bug report.
18	Find exact file:line of wrong behavior.
19	Name root cause in one caveman sentence.
20
21	### 2. ANALYZE
22	Ask three questions:
23	- Would a new §V invariant catch this class of bug? (most common: yes)
24	- Is §I wrong — did spec claim shape the code cannot deliver? (sometimes)
25	- Is §T wrong — did we build the wrong thing? (rare but real)
26
27	### 3. PROPOSE
28	Draft the spec change. Never skip §B; §V/§I/§T are case-by-case.
29
30	Template:
31	```
32	§B row: B<next>\|<date>\|<root cause>\|V<N>
33	§V line: V<next>: <testable rule that would have caught it>
34	```
35
36	Example:
37	```
38	§B row: B3\|2026-04-20\|refund job ran twice on retry\|V7
39	§V line: V7: ∀ refund → idempotency key check before charge reversal
40	```
41
42	### 4. GENERATE TEST
43	New invariant without test = lie. Add failing test first.
44	Name test so it cites the invariant: `TestV7_RefundIdempotent`.
45
46	### 5. VERIFY
47	Fix code. Run test. Must pass. Run full suite. Must not regress.
48
49	### 6. LOG
50	Commit spec edit + test + code fix together.
51	Commit msg: `backprop §B.<n> + §V.<N>: <one-line cause>`.
52
53	## WHAT MAKES A GOOD INVARIANT
54
55	- Testable in code (grep-able or assert-able).
56	- Scoped to a behavior, not a file.
57	- Stated positively when possible (`! hold` over `⊥ forbid`).
58	- References §I surface where it applies.
59
60	Bad: V8: code should be correct.
61	Good: V8: ∀ pg_query ! params interpolated via driver, ⊥ string concat.
62
63	## WHEN NOT TO ADD §V
64
65	- Bug was purely mechanical typo with no class (`i++` vs `i--` in throwaway).
66	- Fix is a one-time migration.
67	- Root cause is external dep (upgrade deps instead, note in §C).
68
69	Still append §B entry — record that this failure mode was considered. Future bug with same smell → §B search shows precedent.
70
71	## OUTPUT SHAPE
72
73	Every backprop run produces:
74	1. §B entry (always).
75	2. §V entry (usually).
76	3. Test file (when §V added).
77	4. Code fix.
78	5. One commit.
79
80	No dashboards. No log files. SPEC.md + git is the full history.

People who liked this also viewed

6 picks

Type