lore

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 choice → DECISIONS.md, a paid-for mistake → LEARNINGS.md. STATE.md is a dashboard, not an archive.

Mode 1 — Session start (resume)

Trigger: a session begins on a project containing docs/lore/, or the user says continue / resume / "where were we".

1. Read docs/lore/STATE.md and docs/lore/ROADMAP.md in full. That is the context load — do not fan out and read the codebase to rebuild context. The point of the lore is to make that unnecessary.
2. Grep LEARNINGS.md for the area about to be touched:

   grep -i -A6 "<area keyword>" docs/lore/LEARNINGS.md
   

   Every entry carries a Trigger: line naming the files or subsystems it applies to, so grep against a filename, module, or tool name.
3. Open only the specific files the task needs.
4. Tell the user briefly, in their language, where things stand and what the next step is per STATE.md — then wait or proceed as they asked.