Specful Adr

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 <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. Under More information, identify the archived original by title and link to its archive path outside docs/adr/ and docs/specs/. An optional pre-adoption path is historical context, not the provenance link. Preserve the archived original unchanged at the linked path; it is never edited into the profile's shape. The maintainer owns retirement under the existing convention; record retirement separately if that convention would otherwise modify or remove the archived original.
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/.