JuliusBrussee/cavekit

# 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

# build — implement spec

Single-thread native plan→execute. You are main Claude. No swarm.

## LOAD

1. Read `SPEC.md`. If missing → tell user to invoke the spec skill first. Stop.
2. Read `FORMAT.md` once if not loaded.
3. Read §R if present — external facts the build must honor, ⊥ re-derive or contradict.
4. Parse invocation args:
   - `§T.n` → that task only
   - `--next` → lowest-numbered row with status `.` or `~`
   - `--all` or empty → every `.` row in §T order

# caveman — spec encoding

Applies to SPEC.md writes, spec-referencing prose, backprop entries.
Does NOT apply to code, error strings, commit messages, PR descriptions.

## GRAMMAR

- Drop articles (a, an, the).
- Drop filler (just, really, basically, simply, actually).
- Drop aux verbs where fragment works (is, are, was, were, being).
- Drop pleasantries.
- No hedging (skip "might", "perhaps", "could be worth").
- Fragments fine.
- Short synonyms: fix > implement, big > extensive, run > execute.

# check — drift report

Pure diagnostic. Reports violations. Writes nothing. User decides remedy.

Spec drifting silently from code is the #1 SDD failure mode. check is the
detector. Run it after each `/build` and before each ship — drift caught here is
a diff; drift caught in prod is a §B.

## LOAD

1. Read `SPEC.md`. If missing → "no spec, nothing to check." Stop.
2. Parse invocation args:
   - `§V` → check invariants only (default)
   - `§I` → check interfaces

# deepen — make modules deep

**Behavior is sacred: tests green before AND after. Every change shrinks an interface or hides a decision — deepen, don't churn.**

A **deep module** hides a lot behind a small interface; a **shallow** one's
interface costs as much to use as writing the code yourself. Complexity =
dependencies + obscurity, and it compounds. Deepen spends spare usage paying
that down *before* it becomes a §B. Run it when the build is green & you have
budget to drain — not under deadline.

## WHEN TO DEEPEN

- Build is green, tests pass, & you have token budget spare.
- A module's interface feels as complex as its implementation (shallow smell).

# grill — sharpen idea before spec

**One question at a time. Every answer lands in a § or gets parked `?`. Never guess a constraint into existence.**

Plan-then-execute guesses the fuzzy parts & builds the wrong thing.
Grill drags the fuzz into §G/§C *before* a single §T row exists.
A bad assumption caught here costs one question. Caught in §B it costs a bug.

## WHEN TO GRILL

- Idea is one sentence & you can feel the holes.
- Multiple readings of the goal exist & you are about to pick one silently.
- Before `/spec new` on anything non-trivial.
- User asks to be challenged / stress-tested.

# research — external knowledge → §R

**Every finding cites a source. No source → flag it `?`, never write a guess as fact.**

"Process without library context gives you well-organized hallucinations."
Build invents a plausible-but-wrong API & §B fills with avoidable bugs.
Research is the external oracle: pull the real fact once, log it caveman, never re-derive.

## WHEN TO RESEARCH

- A §C/§I/§V decision hinges on a lib, API, version, or pattern you are unsure of.
- You are about to assume how an external dependency behaves.
- The idea touches a domain with real prior art (auth, payments, crypto, rate-limit).
- `/grill` parked a `?` that the outside world must answer.

# review — refute the spec before build

**Every finding cites evidence — file:line or a source. No evidence → flag `[unverified]`. Default to refuted: a flaw you cannot prove is a flaw you note, not one you wave through.**

An LLM cannot self-correct on its own judgment — left alone it drifts or
degrades. Review fixes that the only way that works: a *separate* skeptic
anchored to an *external oracle* — the code, §R, the test suite, the docs.
"Looks good" is not a review. A refutation attempt is.

## WHEN TO REVIEW

- Before `/build` on a high-blast-radius change (shared module, auth, data, money, public API).
- Spec touched §I or §V that other code depends on.
- Right-sizing says the cost of a wrong build > the cost of one review pass.

# spec — spec mutator

Read `FORMAT.md` at repo root if not already loaded. Caveman skill applies to all writes here.

## DISPATCH

Inspect user request and project state:

1. No `SPEC.md` at repo root AND args describe idea → **NEW**
2. No `SPEC.md` AND `from-code` in args → **DISTILL**
3. `SPEC.md` exists AND args start `bug:` → **BACKPROP**
4. `SPEC.md` exists AND args start `amend` → **AMEND**
5. `SPEC.md` exists, no args → ask user which mode