Failure Flywheel

Skill: failure-flywheel

Turn recurring failures into rules. Capture by code, count deterministically, draft a stub for a human to approve — never auto-promote.

When to use

• A task failed in a way that could recur (invented an API, broke a test, ignored a rule, over-built). Record it so it is counted, not forgotten.
• Periodically (end of session, or every N failures): --report to see which failure class recurs most.
• When a class crosses the recurrence threshold: --draft <category> to seed a candidate rule, then run /propose to finish it.

Do NOT use to auto-write rules. This skill seeds the gate; a human always approves.

The flywheel (Hamel: create -> label -> fix -> repeat)

The slow human step is "notice the same mistake keeps happening and turn it into a rule." This makes the mechanical 90% deterministic (capture + taxonomy + count + scaffold) and refuses to fake the 10% that needs judgement (what the rule actually is).

Commands

# 1. CAPTURE — append one failure (BY CODE; failures.jsonl is gitignored local history)
python3 harness/scripts/failure-flywheel.py record <category> "<summary>" [--detail "..."]

# 2. REPORT — deterministic taxonomy: group by category, COUNT, leaderboard (most-frequent
#    first) + first/last seen + which classes are eligible to draft
python3 harness/scripts/failure-flywheel.py --report

# 3. DRAFT — only if <category> recurs >= recurrence_threshold: scaffold a STUB proposal at
#    llmwiki/wiki/sources/draft/DDMMYY-failure-<category>.md and STOP for human approval
python3 harness/scripts/failure-flywheel.py --draft <category> [--date YYYY-MM-DD]

Steps

1. On a failure, record it under the closest taxonomy category (see the config). Capture never blocks — an unlisted category is still recorded and flagged in --report.
2. Run --report to read the leaderboard. A class marked DRAFT has recurred >= the threshold.
3. For an eligible class, --draft <category>. It writes a valid draft STUB (OKF frontmatter + ## Origin, deliberately no ## Plan so it passes the R7 gate as a seed) containing a templated "TODO: distill rule from these N failures" + the failure list.
4. The stub STOPS for you. Run /propose to turn it into a complete, gated rule/skill. FailureFlywheel never auto-promotes — the gate stays human.

The adapter boundary (build-now-adapt-later)

Everything above is deterministic and built now. The ONE quarantined unknown is harness/failure-flywheel.config.yaml (verified: false): the recurrence threshold and taxonomy are best-guesses, and the "distill failures -> rule" model is absent. While it is unset, --draft inserts a human-TODO stub instead of an auto-written rule. Finalize later by editing only that one file — calibrate the threshold, name a distill model, flip verified: true.

Rules

• Capture is fail-open — recording a failure must never break the session.
• Never auto-promote. --draft seeds /propose; a human approves.
• The draft filename date is fixed (--date, default 2026-06-29, ISO YYYY-MM-DD only — not the DDMMYY wiki filename convention) for determinism; real use can stamp today. A malformed --date now exits 2 with a clear error instead of silently falling back to the default (fixed 2026-07-20 after that exact silent-fallback shipped a wrong-dated draft file).
• Do not hard-code the threshold or taxonomy anywhere but the config — that is the adapter.

Related

• harness/scripts/code-logger.py — same by-code, gitignored-JSONL, fail-open capture pattern.
• llmwiki/skills/dev-loop/propose.md — the gate this feeds.
• llmwiki/skills/dev-loop/build-now-adapt-later.md — the quarantine pattern the config follows.