writing-specs

1# Writing Specs
2 
3The workflow family's shared bar for every spec a workflow produces: **short, honest, on-rails**.
4Process skills name this concept at the steps that draft or revise specs; *what* to draft and *when*
5stays with the referencing skill. Graph mechanics — frontmatter, link kinds, the `spec_*` tools — are
6the spec-graph skill's ground; this concept carries the quality bar the family holds on top of them,
7and is where the family's rules for specs and the spec graph accrue.
8 
9## Short
10 
11- Small enough to read in one sitting. Target signal, not completeness.
12- Explain intent, not inventory: what the thing is for, what it owns, where its boundary runs — never
13  a file listing or a restatement of the code.
14 
15## Honest
16 
17- Only settled content appears. Never pad with `[TBD]` or placeholder sections — a section that
18  hasn't been settled simply doesn't exist yet.
19- Anything inferred rather than confirmed is marked unconfirmed, inline, where it stands.
20- New and inferred specs are `status: draft` until the user has reviewed them — the flip out of
21  `draft` follows the user's review, never the drafting agent's own judgment. A reviewed durable spec
22  goes `active`, never `done`: it stays in force and evolves with the project.
23 
24## On-rails
25 
26- High-signal enough that a future agent (or human) lands on the decisions without re-deriving them.
27- The spec is the *only* home for rationale: decisions, invariants, trade-offs, and bug post-mortems
28…