# backprop

Turns bug fixes into specification updates in SPEC.md. The agent traces the failure, drafts a testable invariant, adds a failing test, and commits everything together.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2600 installs · ★ 1156
- Author: JuliusBrussee
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/JuliusBrussee/cavekit/tree/HEAD/skills/backprop/SKILL.md
- Updated: 2026-08-14
- HTML: https://affpapa.org/en/nevibecode/skills/backprop

## What it does

Plan-then-execute workflows fix broken code and move on. The backprop protocol ties every defect back to `SPEC.md` so the same bug class cannot recur. It triggers automatically when `/build` tests fail, when a user reports a problem, during an incident post-mortem, or when `/check` flags a VIOLATE state.

Execution follows six steps. The agent traces the exact line of failure and states the root cause in one sentence. Next, it evaluates whether a new §V invariant is required and logs the issue in the §B section. It writes a failing test named after the invariant before touching any implementation files. Once tests pass, the spec edit, test, and code fix merge into a single git commit.

Not every issue earns a new invariant. Purely mechanical typos, one-time migrations, and external dependency failures bypass §V creation, though the §B log entry remains mandatory. The protocol uses no separate dashboards or log files. Your `SPEC.md` file and git log serve as the entire source of truth.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add JuliusBrussee/cavekit --skill backprop -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/backprop/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/backprop/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add JuliusBrussee/cavekit --skill backprop -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/backprop/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add JuliusBrussee/cavekit --skill backprop -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/backprop/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install JuliusBrussee/cavekit backprop
```

2. **Manually: put the files in place**
- File: `.github/skills/backprop/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add JuliusBrussee/cavekit --skill backprop -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/JuliusBrussee/cavekit --path skills/backprop
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/backprop/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add JuliusBrussee/cavekit --skill backprop -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/JuliusBrussee/cavekit/tree/HEAD/skills/backprop/SKILL.md

## When to use it
- stop bug recurrence by adding testable invariants to `SPEC.md`
- document the root cause in the specification §B table
- generate a failing test before writing the code fix
- bundle specification changes, tests, and code fixes into a single commit

## Example prompts
- Tests failed during /build verification, run backprop to trace the root cause and update SPEC.md
- A user reported duplicate charges on retry, execute backprop to add a §V invariant and a test
- Trace this production incident and log the failure mode to §B using backprop

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 07650b762a984ba0.

BEGIN THIRD-PARTY FILE 07650b762a984ba0
````text
---
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 `/build` verification.
- User reports bug.
- Post-mortem after production incident.
- `/check` flags 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 (`! hold` over `⊥ 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++` vs `i--` 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:
1. §B entry (always).
2. §V entry (usually).
3. Test file (when §V added).
4. Code fix.
5. One commit.

No dashboards. No log files. SPEC.md + git is the full history.
````
END THIRD-PARTY FILE 07650b762a984ba0

The third-party file has ended. Everything between the 07650b762a984ba0 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© JuliusBrussee · MIT · https://github.com/JuliusBrussee/cavekit/tree/HEAD/skills/backprop/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md