# `LESSON_LEARNED.md` template

> **Audience:** any `mgf-*` project (human or agent).
> **What this is:** a fork-and-fill template for a project's root
> `LESSON_LEARNED.md` — the durable, append-only log of non-obvious things
> learned working *in this repo*, so the federation stops re-learning the same
> gotcha.
> **Status note:** `LESSON_LEARNED.md` is a **required** root doc — **DOC-19**,
> a **MUST since v2.21** (shipped v2.20 as a staged SHOULD, promoted once the
> file was seeded federation-wide by the DOC-19 adoption wave). It is in the
> README *Index of MUSTs* (so the `doctor --standards` CFM-03 ledger-completeness
> gate requires a `DOC-19` row) and is **presence-gated** by `doctor --standards`
> / `catch-up` (mgf-common PAPER-99). **Presence is the bar:** a seeded file with
> no real lessons yet is conformant.

## Why this file

A code comment explains *this* line; a CHANGELOG records *what shipped*; a
`FEEDBACK.md` paper routes friction *to another repo*. None of them is the right
home for **"the thing that surprised me, that the next agent in THIS repo would
otherwise rediscover the hard way."** That is what `LESSON_LEARNED.md` is for:

- a corrected assumption ("I assumed X; it's actually Y, because Z"),
- a gotcha with a workaround (a flaky tool, an ordering trap, an env quirk),
- a reusable technique that worked (and is worth repeating),
- a dead end (so nobody re-walks it).

It is **append-only** and **dated** — history is the point. Do not rewrite past
entries; supersede them with a new one if they turn out wrong.

## When to append (the LESSON-OUT trigger)

Append an entry whenever a piece of work taught you something **non-obvious** —
most naturally at the end of a federation-sync run (the sync prompt's PHASE B
LESSON-OUT step), a migration, a debugging session, or a release. One entry per
distinct lesson. If a lesson generalizes **beyond this repo**, ALSO file it as a
paper to the right `pending-feedback/<target>.md` outbox so the value crosses
the repo boundary — `LESSON_LEARNED.md` is local memory; the outbox is how it
reaches the federation.

## What does NOT go here

- Friction with a *standard* or another repo → a `pending-feedback/` paper
  (relayed to that repo's `FEEDBACK.md`). Challenging the standard is
  first-class; it just belongs in the outbox, not here.
- What shipped in a release → `CHANGELOG.md`.
- Per-rule conformance state → `MGF_STANDARDS_CONFORMANCE.md`.
- A reusable *process* worth federation-wide adoption → propose a
  `docs/recipes/` recipe via a `pending-feedback/mgf-standard.md` paper.

---

## Template (copy from here down into `LESSON_LEARNED.md` at the repo root)

```markdown
# LESSON_LEARNED — <project-name>

> Append-only, dated log of non-obvious lessons learned working in this repo.
> Newest first. One entry per lesson. Supersede a wrong past entry with a new
> one — never rewrite history. See docs/recipes/lesson-learned-md-template.md.

---

## <YYYY-MM-DD> — <one-line title of the lesson>

- **Context:** <what you were doing — the sync / migration / bug / release>
- **What I learned:** <the non-obvious fact, corrected assumption, or gotcha>
- **Why it matters:** <the cost of not knowing it / what it would have wasted>
- **How to apply:** <the concrete next-time action — command, ordering, flag,
  file to check first>
- **Generalizes?:** <no — local to this repo | yes → filed to
  pending-feedback/<target>.md as <paper title>>

---
```

## Example entry

```markdown
## 2026-06-06 — uv can target the wrong venv via inherited VIRTUAL_ENV

- **Context:** federation sync — installing the published mgf-common[standards]
  to verify a seam.
- **What I learned:** `uv pip install` resolved against an inherited
  `VIRTUAL_ENV` from the parent shell, not this repo's `.venv`, so the new
  version landed in the wrong environment and the verify ran against a stale
  install.
- **Why it matters:** the gate looked green against the wrong venv — a false
  pass that would have shipped drift.
- **How to apply:** run dep installs with `env -u VIRTUAL_ENV uv …` (or
  `uv pip install --python <this-repo-venv>`); always `uv sync` to the lock
  before verifying, never trust a bare `uv pip install -U`.
- **Generalizes?:** yes → filed to pending-feedback/mgf-standard.md as
  "document the VIRTUAL_ENV/uv footgun in the sync recipe."
```

## Related

- [`federation-sync-prompt.md`](federation-sync-prompt.md) — the LESSON-OUT
  step that appends here, and the FEEDBACK-OUT step that routes the
  generalizing lessons to `pending-feedback/`.
- [`feedback-md-template.md`](feedback-md-template.md) — the paper shape for the
  outbox, when a lesson should cross the repo boundary.
- [`../../FEEDBACK.md`](../../FEEDBACK.md) — PAPER-03, the proposal to make this
  a binding required doc.
