`. Never hand-allocate an identifier; the command owns the counter. A decision recorded before the profile existed enters it the same way: scaffold a new record, carry the original decision date in `decided-on` and the re-recording date in `recorded-on`, name the older record by its title and original path under More information, and then retire that older record under its own convention; Git holds its history at that path afterwards. It is never edited into the profile's shape. 3. Complete the placeholders. State the decision in present tense; represent the credible alternatives honestly rather than as strawmen for a preferred answer; record negative consequences with the same care as positive ones. An ADR with no credible alternative or no downside is advertising, not a decision record. 4. Lifecycle belongs to the maintainer: a new record starts proposed, and only the maintainer accepts, rejects, or supersedes. Once accepted, a record is never rewritten, only superseded, except More information, which may be edited in place since it is evidence depth rather than part of the decision event. 5. Run `specful index`, then `specful validate`; commit the regenerated views with the change. Use `specful-review` when the adopting repository requires substantive review or the user asks for it. For the full ADR profile and field-by-field guidance, see <https://unkos-dev.github.io/specful/>.

--- name: specful-adr description: >- Use when recording a durable decision as a Specful ADR (architecture decision record), or superseding an accepted one. compatibility: Requires the specful CLI on PATH. --- # Recording a Specful ADR An ADR records why a durable decision was made: the forces, the credible alternatives, and the consequences. It is not a Requirement (what the software must do) and not a Design (how the system works); if the change is about what or how, load `specful-requirement` or `specful-design` instead. Keep it at decision level: no task sequences, file inventories, or progress notes. ## Workflow 1. Read `docs/adr/` and its index for the numbering, statuses, and the decisions already on record; a new ADR that contradicts an accepted one supersedes it rather than silently disagreeing. 2. Scaffold with `specful new adr --title `. Never hand-allocate an identifier; the command owns the counter. A decision recorded before the profile existed enters it the same way: scaffold a new record, carry the original decision date in `decided-on` and the re-recording date in `recorded-on`, name the older record by its title and original path under More information, and then retire that older record under its own convention; Git holds its history at that path afterwards. It is never edited into the profile's shape. 3. Complete the placeholders. State the decision in present tense; represent the credible alternatives honestly rather than as strawmen for a preferred answer; record negative consequences with the same care as positive ones. An ADR with no credible alternative or no downside is advertising, not a decision record. 4. Lifecycle belongs to the maintainer: a new record starts proposed, and only the maintainer accepts, rejects, or supersedes. Once accepted, a record is never rewritten, only superseded, except More information, which may be edited in place since it is evidence depth rather than part of the decision event. 5. Run `specful index`, then `specful validate`; commit the regenerated views with the change. Use `specful-review` when the adopting repository requires substantive review or the user asks for it. For the full ADR profile and field-by-field guidance, see <https://unkos-dev.github.io/specful/>.