promote-lessonlisted

# promote-lesson The harness is supposed to learn from its mistakes. This skill is the **learning mechanism** — it scans `docs/lessons.md` for repeated pain, then turns the worst-offender lessons into hard rules in `CLAUDE.md`. ## When to use - After a `/review-harness` flagged "promote candidates" - Monthly hygiene (alongside `/review-harness`) - Whenever you find yourself thinking "we just hit this *again*" ## When NOT to use - Right after seeding `docs/lessons.md` — give it 2-4 weeks of real use first - When `docs/lessons.md` has fewer than ~5 entries — sample too small - For one-time observations — wait for a second occurrence before promoting --- ## Why this exists (the research backbone) The **ACE paper (arxiv 2510.04618)** demonstrates that an evolving rulebook works best when: 1. Rules are stored as **structured bullets with IDs** (so individual rules can be targeted) 2. Updates happen via **delta edits**, not full rewrites (so the rulebook accumulates without churn) 3. Promotion is gated by a **helpful/harmful counter** (so noise doesn't pollute the rulebook) Concretely: when the same lesson keeps being referenced — by you, by `/review-harness`, by past PRs — that lesson has earned a place in the always-loaded section. Otherwise it stays in `docs/lessons.md` where it's only consulted on demand. Industry data on why this matters: **45% of AI-generated code contains security flaws** (Veracode 2025), and the bulk of those flaws cluster around the same handful