dx-lesson

Capture one finding so a future change re-reads it instead of relitigating it. A lesson is scar tissue or a load-bearing decision — a rule, not a story. Two flavors, both belong here: cautionary ("this broke because…") and decisional ("we chose X over Y because Z", including a rejected refactor: "don't re-deepen X — it's shallow on purpose because Y"). This is the anteroom to a standard, not an ADR — the framework has no separate decision register.

Guard. foundation/lessons.md must exist (it does after /dx-init). If it is missing, tell the user to run /dx-init first. Read foundation/glossary.md for naming — a one-line habit, no section.

1 — Get the finding

Take the finding from the argument. If nothing was passed, ask what broke or what was decided, and why it matters — one question, then proceed. Don't turn a capture into an interview.

2 — Load the entry shape (invoke dx-references with knowledge-layer)

Use it for the lesson entry shape and to judge whether this is a lesson at all (a one-off finding is fine here; a recurring one is a promotion candidate — see step 4).

3 — Append (never rewrite)

Append to the end of foundation/lessons.md. Never edit, reorder, dedupe, or reformat existing entries — the file is append-only; that friction is the point. One entry, this shape: