spec-graph

1# Spec graph
2 
3## Specs are the ground truth
4 
5- Specs describe the architecture, decisions, contracts, and boundaries behind the code — the intent
6  that the code alone does not reveal. Treat them as authoritative.
7- **Consult the owning spec when it governs the work.** When work depends on, checks, explains, or
8  may alter a documented boundary, contract, invariant, behavior, or architecture decision, use
9  `spec_grep` / `spec_get` / `spec_graph` to find the applicable record and align with it. If a change contradicts a recorded
10  decision, surface and reconcile the contradiction rather than silently diverging.
11- **Keep lookup proportional.** Specs are the map for decisions and boundaries; code confirms the
12  implementation. A localized fix, explanation, or check that changes no documented decision may
13  inspect only the files it needs without reading unrelated specs.
14- **Keep them honest.** A change that moves or blurs a boundary, or overturns a decision, updates the
15  spec as part of the same change. Specs that drift from the code stop being ground truth.
16 
17## What a spec is
18 
19- A durable, declarative document. It states the world as it is — the intent, decisions, contracts, and
20  boundaries behind the code — not plans, tasks, phases, or a work journey.
21- Concise and readable. It captures what is *not* obvious from the code; it never restates the code.
22- The bar: reading the relevant specs should be enough to understand an area and to formulate a task to
23  improve it.
24…