write-spec

Write Spec

Turn accepted ADRs into formal implementation contracts. A spec defines the exact interface, behavior, and constraints that code must satisfy.

Skip for: decisions that don't need formal contracts (tooling config, doc conventions), or when the ADR itself is specific enough to implement from directly.

Process

1. Gather Input

Read the accepted ADR(s) that led to this spec. Read the idea docs they reference. Identify what the spec must formalize — the ADR decided what, the spec defines how exactly.

2. Interview About the Contract Boundary

Walk through each branch of the contract, resolving ambiguity:

• Types: What are the exact data structures? Field names, types, optionality, invariants.
• Functions/Messages: What are the signatures? Parameters, return types, error types.
• Error Cases: What can go wrong? How is each error reported? What does the caller do?
• Edge Cases: Empty input, maximum sizes, concurrent access, version mismatches.
• Constraints: Performance budgets, memory limits, security requirements.
• Ordering: Are operations sequential, concurrent, or unordered? What happens during races?

For each question, provide a recommended answer. If the answer requires exploration (reading existing code, checking a dependency's API), do the exploration.

3. Sketch Bounded Concerns

Identify if this spec should be one document or split into multiple specs. One spec per bounded concern:

• One API surface (plugin API, config API, agent control API)
• One wire protocol (daemon↔client IPC, remote access WebSocket)
• One data format (session serialization, scroll buffer archive format)

Look for opportunities to extract deep modules — interfaces that encapsulate complexity behind a simple, testable boundary that rarely changes.

4. Write the Spec

Use the project's spec template (docs/specs/0000-template.md). Every section must be concrete:

Overview: One paragraph — what this spec defines and why.

Contract: The formal definition. No hand-waving. Every type is defined. Every function has a signature. Every message has a format. If referencing an IDL file (.proto, .wit), the IDL is the source of truth and the spec explains behavior and constraints the IDL can't express.

Behavior: Expected behavior for normal and error cases. Edge cases called out explicitly. State transitions documented if applicable.

Constraints: Performance budgets, memory limits, security requirements, backward compatibility guarantees.

References: Link to the ADR(s) that led here and the idea doc(s) for broader context.

5. Rigor Check

Before presenting the spec:

• Every type is fully defined (no TBD, details later, to be determined)
• Every function/message has input types, output types, and error types
• Every error case has a defined behavior (what happens, what the caller sees)
• Edge cases are called out (empty, maximum, concurrent, disconnected)
• Constraints are measurable (not "fast" but "< X ms" or "competitive with Y")
• All ADR decisions are reflected in the spec
• Cross-references link to real docs
• If an IDL file is referenced, its path is specified

6. Checks

• mise run fmt — format
• mise run lint — lint
• /de-slopify on all prose
• Verify frontmatter is complete (spec number, title, status: draft, date, ADR references, tags)
• Check all cross-references resolve

7. Update Index

• Add the new spec to the index table in docs/specs/README.md.
• Update cross-references in related ADR and idea docs if needed.

8. Commit Gate

Present the spec summary and wait for explicit "commit" before committing.

Common Mistakes

Output

A spec file at docs/specs/NNNN-short-title.md following the project template. If the spec references an IDL, the IDL file path is specified (the file itself may not exist yet — the spec is the contract, the IDL is generated during implementation).