lorelisted

# Lore A project's real knowledge is not in its code. Code shows *what* exists; it never shows what was tried and abandoned, why one approach beat another, or which trap costs an hour every time someone forgets it. Without that record, every new session re-derives it — usually by re-reading the whole repo, sometimes by repeating a mistake that was already paid for once. This skill maintains that record as five files under `docs/lore/`, and defines when to read each and when to write to it. ## The files | File | Holds | Read when | |---|---|---| | `STATE.md` | Current status: what works, what's mid-flight, active blockers, next steps. **The entry point.** | Every session start — always, fully | | `ROADMAP.md` | Phased progress path with checkboxes. Where the project is going. | Session start; when picking the next task | | `DECISIONS.md` | Dated decisions: what was chosen, why, what was rejected. | Before changing anything architectural; when asked "why is it like this?" | | `LEARNINGS.md` | Traps, failed approaches, dead ends. Each entry has a `Trigger:` line. | Grep before touching an area — see below | | `JOURNAL.md` | Append-only dated work log. Raw history. | Rarely — only to reconstruct a specific past session | **Size discipline:** `STATE.md` stays under ~150 lines. It is the only file read in full every session, so it must describe the present, not accumulate history. When something in it becomes past tense, move it: a finished task → `JOURNAL.md`, a resolved choi