`. Never hand-allocate an identifier; the command owns the counter. 3. Complete the placeholders. Declare the Requirements the Design `satisfies` and cite governing ADRs through `governed-by`, naming only the ADR whose rationale this subject embodies, never a related or organising decision such as the decision to adopt a convention, and omit the field when that record does not exist in the profile. Describe the subject as it is, at the level a maintainer needs to change it safely; decision rationale belongs in an ADR, not here. More information is optional and is removed completely when it adds nothing; it never restates a `satisfies` or `governed-by` edge as a link, since `specful show` already renders those. 4. Run `specful index`, then `specful validate`; commit the regenerated views with the change. 5. Mechanical validation does not judge substantive quality. Use `specful-review` when the adopting repository requires substantive review or the user asks for it. For the full Design profile and field-by-field guidance, see <https://unkos-dev.github.io/specful/>.

--- name: specful-design description: >- Use when writing or updating a Specful Design: documenting how a subject of the system works, or connecting a Design to the Requirements it satisfies. compatibility: Requires the specful CLI on PATH. --- # Writing a Specful Design A Design describes how a subject of the system works now, written as though it has always worked this way. It is not a Requirement (what the software must do) and not an ADR (why a decision was made); if the change is about what or why, load `specful-requirement` or `specful-adr` instead. History and transitions never appear in the prose: a transition is a plan, and what used to be true is Git history. ## Workflow 1. Start at `docs/specs/index.md` and follow the scope indexes to the subject's module. Read the neighbouring Designs and the Requirements they satisfy before writing. 2. Scaffold with `specful new design --title `. Never hand-allocate an identifier; the command owns the counter. 3. Complete the placeholders. Declare the Requirements the Design `satisfies` and cite governing ADRs through `governed-by`, naming only the ADR whose rationale this subject embodies, never a related or organising decision such as the decision to adopt a convention, and omit the field when that record does not exist in the profile. Describe the subject as it is, at the level a maintainer needs to change it safely; decision rationale belongs in an ADR, not here. More information is optional and is removed completely when it adds nothing; it never restates a `satisfies` or `governed-by` edge as a link, since `specful show` already renders those. 4. Run `specful index`, then `specful validate`; commit the regenerated views with the change. 5. Mechanical validation does not judge substantive quality. Use `specful-review` when the adopting repository requires substantive review or the user asks for it. For the full Design profile and field-by-field guidance, see <https://unkos-dev.github.io/specful/>.