# Lessons Learned — Index

This directory holds one lesson per file. Each lesson is a structured record of something that went wrong, why, and the rule to follow going forward.

- **Add a lesson:** copy `_TEMPLATE.md` to `tasks/lessons/<YYYY-MM-DD>-<slug>.md` and fill it in.
- **Surface critical rules:** set `top_rule: true` in the frontmatter. The *Top Rules* section below is auto-generated and loaded at every session start.
- **Group by topic:** set `applies_to: [topic1, topic2]` (typed) to surface a lesson under the right heading in *Active Rules By Topic*.
- **Refresh:** run `/lesson-refresh` periodically to keep/update/archive lessons that have drifted.
- **Regenerate this index:** run `./scripts/lesson-graph.sh` to validate the typed-relation graph and rewrite the auto sections. Use `--check` for a CI-friendly validation-only pass.

The four sections below (Top Rules, Active Rules By Topic, Recently Added, Superseded) are **auto-generated** between `<!-- BEGIN/END AUTO-GENERATED ... -->` markers — never edit them by hand. Change the underlying lesson frontmatter and re-run `lesson-graph.sh`.

---

## Top Rules

<!-- BEGIN AUTO-GENERATED top-rules (managed by scripts/lesson-graph.sh) -->
*No top rules yet. Set `top_rule: true` in a lesson's frontmatter to surface it here.*
<!-- END AUTO-GENERATED top-rules -->

## Active Rules By Topic

<!-- BEGIN AUTO-GENERATED by-topic (managed by scripts/lesson-graph.sh) -->
### scope-discipline

- **Edited wrong tsconfig and broke the build** ([2026-04-15-example-tsconfig](2026-04-15-example-tsconfig.md))

### tooling

- **Edited wrong tsconfig and broke the build** ([2026-04-15-example-tsconfig](2026-04-15-example-tsconfig.md))
<!-- END AUTO-GENERATED by-topic -->

## Recently Added

<!-- BEGIN AUTO-GENERATED recently-added (managed by scripts/lesson-graph.sh) -->
*No lessons created in the last 30 days.*
<!-- END AUTO-GENERATED recently-added -->

## Superseded

<!-- BEGIN AUTO-GENERATED superseded (managed by scripts/lesson-graph.sh) -->
*No superseded lessons. Older lessons get this status when a newer lesson lists them in `supersedes:`.*
<!-- END AUTO-GENERATED superseded -->

---

## Format Reference

Each lesson file uses YAML frontmatter + the structure in `_TEMPLATE.md`:

| Field | Purpose |
|---|---|
| `title` | One-line summary, shown in the auto sections above |
| `created` / `updated` | ISO dates (YYYY-MM-DD) |
| `tags` | Free-form list for grep/filter (untyped) |
| `problem_type` | `tool` \| `process` \| `bug` \| `knowledge` |
| `source` | `correction` (user fixed agent) \| `review` (caught in code review) \| `discovery` (agent self-noticed) |
| `confidence` | `high` \| `medium` \| `low` — how sure are you the rule generalizes |
| `top_rule` | `true` to surface under *Top Rules* |
| `status` | `active` \| `archived` \| `superseded` |
| `related` | Free-form slugs of related lessons (legacy; kept for backward compat) |
| `supersedes` | **Typed.** Slugs of older lessons this one replaces. Older lessons should set `status: superseded`. |
| `applies_to` | **Typed.** Canonical topic tags (e.g. `scope-discipline`, `plan-first`, `verification`). Powers *Active Rules By Topic*. |
| `contradicts` | **Typed.** Slugs of lessons whose rule conflicts with this one. The graph script warns on mutual loops. |
| `related_decisions` | **Typed.** ADR slugs from `tasks/decisions.md` (e.g. `adr-003`). |

Body sections: **Issue** → **Root Cause** → **Rule** → optional **Verification** → optional **References**.

---

## Lifecycle

| Stage | Trigger | Action |
|---|---|---|
| Capture | User correction, review finding, or own discovery | Copy `_TEMPLATE.md`, fill in, save as `<YYYY-MM-DD>-<slug>.md` |
| Promote | A lesson repeats or proves critical | Set `top_rule: true`; `lesson-graph.sh` surfaces it automatically |
| Replace | A newer lesson refines/replaces an older one | Set `supersedes: [<old-slug>]` on the new lesson; set `status: superseded` on the old one |
| Encode | A lesson becomes a hook, lint rule, or CLAUDE.md rule | Set `status: superseded`; note the location in References |
| Archive | A lesson no longer applies (code changed, dep removed) | Set `status: archived` |
| Refresh | Periodic (`/lesson-refresh` skill) | Re-evaluate all `active` lessons; consume graph signals |

The goal is a **small** set of `top_rule: true` lessons that the agent sees at boot, with the rest discoverable via topic, recency, or supersession chains.