| name | architectural-decision-records |
| description | Use when documenting, drafting, reviewing, or updating ADRs, decision logs, tradeoffs, rationale, consequences, alternatives, or architecture decision history. |
| license | MIT |
| compatibility | Codex lazy-loaded skill for OpenSpec projects. |
Architectural Decision Records
Use this optional skill only after recommendation and user consent.
An ADR captures one architecturally significant decision, its rationale,
tradeoffs, status, and consequences. Optimize for future maintainers who need
to reconstruct why a decision was made.
Workflow
- Identify the single decision. Split bundles into multiple ADRs.
- Check
preferences.md for preferred-style.
- If unset, ask the user which style to remember before drafting.
- Use the matching template in
templates/.
- Capture known facts only. Mark missing evidence as
Unknown or ask a
focused question.
- Preserve history. Supersede old accepted ADRs instead of rewriting them away.
Status Values
- Proposed: under review.
- Accepted: committed decision.
- Deprecated: historically relevant but no longer recommended.
- Superseded: replaced by another ADR.
Review Checklist
- One decision, not a bundle.
- Context explains why the decision exists.
- Rejected options and tradeoffs are explicit.
- Rationale is tied to requirements and constraints.
- Downsides and follow-up work are recorded.
- Unknowns are marked, not invented.
