78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
|
---
|
||
|
|
name: backprop
|
||
|
|
description: >
|
||
|
|
Bug-to-spec feedback loop: when a bug occurs or test fails, traces root cause,
|
||
|
|
adds an invariant (§V) to prevent recurrence, logs to §B, and binds a regression test.
|
||
|
|
Use on test failure during build, user bug report, post-mortem, or when asked to "backprop".
|
||
|
|
concerns: [system-one-balance]
|
||
|
|
---
|
||
|
|
|
||
|
|
# Backprop — Bug → Spec Feedback Loop
|
||
|
|
|
||
|
|
Plan-then-execute fixes the code and forgets.
|
||
|
|
Spec-Driven Development fixes the code AND amends the spec so recurrence is impossible.
|
||
|
|
That feedback loop is **backprop**.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 0: Setup and Protocols
|
||
|
|
|
||
|
|
1. **Governing Invariants**:
|
||
|
|
- Every bug gets a row in the §B table of `SPEC.md`.
|
||
|
|
- Behavioral bugs should be paired with a new §V invariant whenever a rule can prevent recurrence.
|
||
|
|
- A new invariant without an automated test is incomplete: always pin with a test citing the invariant.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 1: Ingest and Check
|
||
|
|
|
||
|
|
1. Parse the failure input: test failure traceback, reproduction log, or user bug report.
|
||
|
|
2. Confirm `SPEC.md` exists; if absent, invoke `spec distill` or create it before logging.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 2: Processing (Core Logic)
|
||
|
|
|
||
|
|
### Step 1: Trace Root Cause
|
||
|
|
- Locate the exact file and line producing the incorrect behavior.
|
||
|
|
- State the root cause in one crisp Caveman sentence.
|
||
|
|
|
||
|
|
### Step 2: Invariant Formulation
|
||
|
|
Evaluate:
|
||
|
|
- Would a testable §V invariant prevent this entire class of bug? (Commonly yes).
|
||
|
|
- Did the interface definition (§I) promise a shape the code cannot deliver?
|
||
|
|
- Was a task (§T) misunderstood or incomplete?
|
||
|
|
|
||
|
|
Draft the proposed additions:
|
||
|
|
```text
|
||
|
|
§B row: B<next>|<date>|<root cause>|V<N>
|
||
|
|
§V line: V<next>: <testable rule that would have caught it>
|
||
|
|
```
|
||
|
|
|
||
|
|
### Step 3: Pin Reproduction Test
|
||
|
|
- Author a failing regression test before modifying application code.
|
||
|
|
- Name the test to cite the invariant: e.g. `test_v7_refund_idempotent()`.
|
||
|
|
|
||
|
|
### Step 4: Implement Fix & Verify
|
||
|
|
- Apply minimal surgical code fix.
|
||
|
|
- Run the regression test to confirm green.
|
||
|
|
- Run the full project test suite to verify no collateral regressions.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 3: The System One Balance Pass
|
||
|
|
|
||
|
|
- **Augment, Don't Handcuff**:
|
||
|
|
- Do NOT invent artificial §V rules for one-off typos or transient external network outages (log in §B, but skip §V).
|
||
|
|
- State invariants positively where possible (`! hold` rather than complex negative conditionals).
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Phase 4: Output Execution & Verification
|
||
|
|
|
||
|
|
Every complete backprop run produces:
|
||
|
|
1. Append to §B table in `SPEC.md`.
|
||
|
|
2. Append to §V invariants (when applicable).
|
||
|
|
3. Passing regression test.
|
||
|
|
4. Minimal code fix.
|
||
|
|
5. Atomic git commit: `backprop §B.<n> + §V.<N>: <one-line cause>`.
|