FormSpec Docs

You are generating user-facing documentation derived from the system's design documents and formal specification. Documentation is a downstream artifact — it must be consistent with the spec, and link back to design documents where appropriate.

Steps

1. Read all artifacts

Read:

spec/system.md
All feature design docs: Glob for spec/features/*/design.md
All feature plans: Glob for spec/features/*/plan.md
spec/formal/traceability.md
Existing documentation in the project root and docs/ directory (Glob for *.md, docs/**/*.md, excluding spec/)

All spec artifacts must exist. If spec/system.md or feature design docs are missing, direct the user to the prerequisite commands (/formspec.init.0, /formspec.design.1) and stop.

2. Determine documentation scope

From the design artifacts, identify what needs to be documented:

System-level overview and purpose (from spec/system.md)
Per-feature user-facing behavior (from feature design docs — user stories, success criteria)
Configuration, setup, and usage (from feature plans — technology choices, architecture)
API contracts and interfaces (from design docs — Interface Contract sections are the primary source; user stories describe the behavior behind those interfaces)
Behavioral guarantees the system makes (from traceability — which formal properties translate to user-visible promises)

Not everything in the design docs belongs in user documentation. Filter out:

Internal implementation details that users don't interact with
Pathological/adversarial use cases (these inform testing, not docs)
TLA+ specifics (the formal spec is developer-facing, not user-facing)

3. Generate or update documentation

Create or update documentation files. The exact structure depends on the project — adapt to what already exists. Typical outputs:

README.md (if it doesn't exist or needs updating):

Project description derived from spec/system.md System Overview
Setup and usage instructions derived from feature plans' technology choices
Feature descriptions derived from feature design docs

docs/ (for projects complex enough to warrant separate pages):

Per-feature documentation derived from the feature's user stories and success criteria
API reference derived from the Interface Contract sections in design docs (schemas, request/response formats, error conventions)
Configuration reference derived from architectural constraints and plan

4. Add spec traceability

Documentation should link back to design documents where it describes feature behavior. Use inline references so that readers (and /formspec.check.8) can trace documentation claims to their source:

<!-- spec: features/2026-02-10-user-auth/design.md#US-1 -->

These comments serve two purposes:

Readers can find the detailed design behind a documented behavior
The check command can verify documentation hasn't drifted from the spec

Every documented behavioral claim (what the system does, guarantees it makes, constraints it enforces) should have a traceability comment linking to the design requirement it derives from.

5. Validate documentation against spec

Before finishing, cross-check:

Every user story marked as user-facing in the design docs has corresponding documentation
No documentation claims contradict the design documents or formal properties
Behavioral guarantees stated in docs are actually verified (cross-reference with traceability.md)
Links to design documents are valid (files exist, requirement IDs match)

Flag any discrepancies found.

6. Report

Summarize what documentation was created or updated, which design documents it traces to, and any gaps where documentation could not be generated (e.g., design doc lacks enough detail for user-facing docs). Suggest running /formspec.check.8 to validate full cross-artifact consistency.

4 KiB Raw Blame History