Zen spec

Translate the agreed destination into behavior an implementer and reviewer can verify independently. Do not interview the owner again for facts already established.

1. Read the originating idea, decision ledger/glossary, RDT findings, selected ART/SRT and actual code in the affected path. Distinguish confirmed requirements from assumptions and unresolved owner decisions.
2. Describe the problem, actors and outcomes. Maintain a coverage ledger for every requested capability, including deferred items. Out-of-scope items must reflect an actual boundary or owner decision, not silent scope reduction.
3. Specify observable behavior: normal flow, empty/loading/error/disconnected/conflict states, data ownership, permission boundaries and failure/recovery semantics. Describe relevant schemas, identifiers, state transitions and interface contracts. Link source locations with the revision rather than treating filenames as permanent architecture.
4. Preserve selected prototype decisions precisely; include a small state machine or type only when it encodes an agreed contract better than prose. Do not equate an illustrative preview with a working integration.
5. Write acceptance criteria as observable outcomes with a concrete trigger, expected result and evidence method. Prefer tests at existing behavioral seams. Include negative cases where wrong behavior would matter, such as duplicate commands, stale revisions or unselected-workspace data.
6. Identify dependencies, migration/adoption, compatibility, documentation and rollback needs proportionate to the change. Open decisions stay visibly open, with an owner/resolution method; do not mark a task executable if they determine its acceptance.
7. Save a DOC with data.kind: "spec", linking research, decisions and exact selected variant. Use the specification template and actual record operations, or initialized standalone records. If neither writer exists provide a labelled draft.

Completion and next mode

The specification is ready when scope is represented, consequential assumptions are explicit and each criterion has a verification path. Produce an owner-readable summary of behavior, decisions and remaining blockers. Then use tasks to create demonstrable slices. Do not publish to an issue tracker, start a model or commit simply because an upstream spec workflow does so.

Example: “An offline edit remains Pending device until one acknowledged Markdown revision exists” is testable. “Sync works” is not. A mock adapter can prove the write pipeline, but real-provider acceptance must remain a separate criterion.