spec-graph

Spec graph

Specs are the ground truth

• Specs describe the architecture, decisions, contracts, and boundaries behind the code — the intent that the code alone does not reveal. Treat them as authoritative.
• Reach for the spec tools first. Whenever you set out to explore the project, plan a change, investigate an area, or work with specs in any way, your first move is the spec tools (spec_grep / spec_get / spec_graph) — before grep, find, or reading source. The specs are the map; the code is the territory you confirm against it.
• Start from the specs, not the code. To understand an area or plan a change, read the relevant specs first and use them as the map; read code second, to confirm details.
• Check work against them. Before introducing a decision, a contract, or a boundary change, find what the specs already say and align with it. If a change contradicts a recorded decision, surface the contradiction and reconcile it — update the spec or change the approach — rather than silently diverging.
• Keep them honest. A change that moves or blurs a boundary, or overturns a decision, updates the spec as part of the same change. Specs that drift from the code stop being ground truth.

What a spec is

• A durable, declarative document. It states the world as it is — the intent, decisions, contracts, and boundaries behind the code — not plans, tasks, phases, or a work journey.
• Concise and readable. It captures what is not obvious from the code; it never restates the code.
• The bar: reading the relevant specs should be enough to understand an area and to formulate a task to improve it.

Keep specs lean

• Explain intent, not inventory. Describe what a module is for, what it owns, and where its boundaries are — not a file-by-file transcript of its directory. The reader can see the files; the spec exists for what the files don't say.
• Record the edges that matter. State the module's boundary (allowed / forbidden deps) and the dependency edges between its sub-modules. List a part only when its role or its edges aren't obvious from its name — e.g. a small table that carries a real dependency DAG earns its place; a table that just pairs foo.ts with "the foo tool" is noise, so say it in a sentence instead.
• Say each thing once. A fact lives in exactly one spec; others link to it by id rather than restate it. If a paragraph is being copied between specs, move it to the spec that owns the concept and point at it. Duplicated prose drifts and turns into contradictions.
• Prefer prose to exhaustive tables, and cut anything that only paraphrases code, filenames, or a sibling spec.