# Specful Adr

> Use when recording a durable decision as a Specful ADR (architecture decision record), or superseding an accepted one.

- Skill: `unkos-dev/specful-adr` (Agent Skill)
- Install (CLI): `npx skillmds@latest add unkos-dev/specful-adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unkos-dev/specful-adr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: unkos-dev (https://skillmd.com/u/unkos-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/unkos-dev/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/>.