| name | expert |
| description | This project's long-term memory — how to run, validate, and extend it; its architecture, patterns, hard invariants, worked examples, and current decisions/direction. Consult when planning a feature, validating a spec, implementing a slice, or writing intent for this project. Routing table below points to one small reference file per topic. |
The Expert — this project's long-term memory
How to use this memory
Scan the routing table, open only the reference files whose USE WHEN matches
the task at hand. Each file is one topic; files cross-link with [[wikilinks]]
(resolve [[name]] to references/name.md). Do not page through everything.
Facts vs. decisions
Most shards describe the code as it IS — plan and build consistently with them. A
decision- shard describes where the project is HEADING; the code may not reflect
it yet.
When your task touches an area a decision covers, make a call: does this work
advance the decision (build the new way) or stay consistent with current
code (build the old way)? Read the decision's "Until fulfilled" note first — it
answers this for its case. If it's silent: new isolated code follows the decision;
changes to existing code stay consistent with what surrounds them, unless the task
is the migration. Never assume a decision is already implemented — verify the
current state in code before planning against it.
Routing table
| Reference | USE WHEN |
|---|
| (empty — the first /learn, Reflect, or your own edit adds the first shard) | |
Writing to this memory
- One topic per file, named
<prefix>-<topic>.md, opening with a USE WHEN: line.
- Anything that helps the next agent belongs here — facts about the code as it
is (cite file paths, shas) AND decisions, direction, and aspirations about where
it's going. Make clear in the prose which is which.
- Facts →
how-to-/concept-/pattern-/invariant-/example-, cited.
Direction (a choice the code hasn't caught up to) → decision-<slug>.md:
the direction and why, a [[concept-…]] pointer to the current state, and an
Until fulfilled: note (what advances the decision vs. what stays consistent
with today's code). No status field — the file existing means it's adopted.
- Reconcile, don't accumulate — when reality or intent changes, edit or delete
the shard. A merge that fulfills a decision promotes it to a
concept-/pattern-
fact and deletes the decision; a decision you've walked back gets deleted, not
appended to.
- Add the routing-table line in the same commit as the shard.
