| name | cmk:adr |
| description | This skill should be used when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern. |
| version | 0.1.0 |
ADR
Create or update architecture decision records for system-level technical choices — databases, protocols, infrastructure patterns, and other decisions with trade-offs that affect multiple features or core architecture.
References
Read references/adr-conventions.md for placement rules and references/adr-template.md for section structure.
Workflow: Create
- Gather decision context from conversation/docs/links.
- Validate scope is system-wide (not feature-scoped).
- Place at the repository's existing ADR path, or fallback:
docs/adrs/{NNNN}-{decision-title}.md. Determine {NNNN} by scanning existing ADRs and incrementing (start at 0001 if none exist).
- Fill template from
references/adr-template.md (or local template if present).
- Set status to
proposed.
Workflow: Iterate
- Read the existing ADR in full.
- Upstream check: If
docs/system-design.md exists, check whether the revised decision conflicts with current architecture. Warn the user if so.
- Identify what changed and why.
- Update in place: revise decision/rationale, update alternatives and consequences, note what shifted.
- Update
Last updated date.
- Transition status:
proposed → accepted when team agrees. accepted stays accepted when decision evolves.
Output
- Create: complete ADR file using canonical naming
- Iterate: update in place with current decision and rationale
- Decision statement is clear and implementable
- Alternatives section is always present with concrete trade-offs
- Consequences section is always present with short-term and long-term impact
- If decision changed, rationale explains what shifted
