---
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>`.