| name | spec-to-adr |
| description | Extract the architectural decisions from a GitHub Spec Kit spec or plan and record them as ADR(s) in the project's MADR format. Use after running /speckit.specify or /speckit.plan, or when the user wants to turn a spec/plan/feature document into Architecture Decision Records. |
spec-to-adr
Bridge the project's spec-driven workflow (GitHub Spec Kit) to its ADRs: read a spec/plan
and capture the decisions it implies as ADRs. Specs describe what to build; ADRs record
why a particular design was chosen — this skill turns the latter out of the former.
This skill composes with write-adr; follow its numbering, MADR
sections, index update, and conventions for every ADR you create.
Inputs
Steps
- Read the spec/plan. If the user didn't name one, list candidates
(
ls specs/*/spec.md specs/*/plan.md and .specify/) and ask which to use.
- Identify decisions. Pull out the genuine architectural choices — not every requirement.
A line deserves an ADR when it (a) is costly to reverse, (b) chooses between real
alternatives, or (c) constrains the architecture. Examples: a storage/transport choice, a
new cross-cutting pattern, a dependency, a public contract. Skip pure implementation detail.
- Confirm scope. Show the user the candidate decision list and how you'd split it (one
ADR per decision; merge tightly-coupled ones). Let them trim before writing.
- Author each ADR via the
write-adr conventions: next number, docs/adr/NNNN-*.md from
docs/adr/template.md, MADR sections, index row. In More Information, link back to the
source spec/plan (specs/<feature>/...) so the ADR and spec stay connected.
- Set status honestly.
Proposed if the spec is approved but the work isn't done;
Accepted only once the decision is settled/implemented.
Notes
- Reuse the spec's own "alternatives considered" / "rationale" sections as the ADR's
Considered Options and Decision Drivers where present — don't reinvent them.
- One spec often yields several ADRs; keep each ADR single-decision and scannable.
- Don't copy requirement lists into ADRs; an ADR is the decision and its rationale, with a
link to the spec for the full requirements.
$ARGUMENTS
