77 lines
4 KiB
Markdown
77 lines
4 KiB
Markdown
---
|
|
description: Generate user documentation derived from the specification
|
|
allowed-tools: [Read, Write, Edit, Glob, Grep, Task]
|
|
---
|
|
|
|
# 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.0.init`, `/formspec.1.design`) 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.8.check`) can trace documentation claims to their source:
|
|
|
|
```markdown
|
|
<!-- 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.8.check` to validate full cross-artifact consistency.
|