tools-only /adr
Create Architecture Decision Records (ADRs) following a standard template with Context, Decision, Rationale, Consequences, and Alternatives Considered. Guides you through capturing the reasoning behind significant architectural choices.
When to Use This Skill
- Recording a significant technical or architectural decision
- Documenting why a particular approach was chosen over alternatives
- Creating a decision log for governance or audit purposes
- Capturing trade-offs discussed in architecture reviews
- Updating or superseding an existing decision
Usage
/adr <title> [--status proposed|accepted|deprecated|superseded]
Parameters
| Parameter | Description | Required |
|---|---|---|
title |
Short title for the decision | Yes |
--status |
Decision status (default: proposed) |
No |
Instructions
Phase 1: Gather Decision Context
Prompt the user for the following information. If they provide partial input, work with what's available and note assumptions.
Required:
| Field | Description | Example |
|---|---|---|
| Title | Short, descriptive title | Use Event-Driven Integration for Order Flow |
| Context | What is the problem or situation driving this decision? | Orders must propagate to 5 downstream systems within 2 seconds |
| Decision | What is being decided? | Adopt Apache Kafka as the event broker |
| Rationale | Why this option over alternatives? | Kafka handles our throughput needs and supports replay |
| Alternatives | What other options were considered? | REST polling, RabbitMQ, AWS SNS/SQS |
Optional:
| Field | Description |
|---|---|
| Deciders | Who participated in the decision? |
| Consequences | What becomes easier or harder as a result? |
| Related decisions | Links to related or dependent ADRs |
| Assumptions | What assumptions underpin this decision? |
| Constraints | What constraints influenced the decision? |
Phase 2: Generate ADR Document
Create the ADR with the following structure:
- Frontmatter — title, type, status, date, deciders, tags
- Context — The problem space and forces at play
- Decision — The chosen approach, stated clearly
- Rationale — Why this option was selected, with evidence
- Consequences — What becomes easier and what becomes harder
- Alternatives Considered — Each alternative with pros/cons and why it was rejected
- Related Decisions — Links to ADRs this depends on, supersedes, or relates to
- Review Date — When this decision should be revisited
Phase 3: Cross-Reference
- Search the vault/repository for existing ADRs that relate to this decision
- Suggest
relatedTo,dependsOn, orsupersedeslinks - If this ADR supersedes another, suggest updating the old ADR's status to
deprecated
Output Format
---
type: ADR
title: "ADR - <Title>"
status: proposed
created: YYYY-MM-DD
deciders:
- "[[Person Name]]"
tags: [domain/architecture, activity/decision]
relatedTo: []
supersedes: []
dependsOn: []
confidence: medium
summary: "<One-line summary>"
---
# ADR - <Title>
## Status
**Proposed** | YYYY-MM-DD
## Context
<What is the issue motivating this decision? What forces are at play?>
## Decision
<What is the change being proposed or decided?>
## Rationale
<Why this option? What evidence supports it?>
## Consequences
### Easier
- <What becomes simpler, faster, or cheaper>
### Harder
- <What becomes more complex, expensive, or constrained>
## Alternatives Considered
### Alternative 1: <Name>
- **Pros:** <advantages>
- **Cons:** <disadvantages>
- **Rejected because:** <specific reason>
### Alternative 2: <Name>
- **Pros:** <advantages>
- **Cons:** <disadvantages>
- **Rejected because:** <specific reason>
## Assumptions
- <Key assumptions underpinning this decision>
## Related Decisions
- Depends on: <linked ADRs>
- Related to: <linked ADRs>
## Review Date
This decision should be revisited by YYYY-MM-DD or when <trigger condition>.
Examples
Example 1: Integration Pattern Decision
/adr Use Event-Driven Integration for Order Processing
Generates an ADR capturing the decision to use Kafka for order event propagation, with REST polling and message queues as rejected alternatives.
Example 2: Database Technology Choice
/adr --status accepted Adopt PostgreSQL for Transactional Data
Generates an accepted ADR documenting the choice of PostgreSQL over MySQL and DynamoDB for the transactional data store.
Example 3: Superseding a Previous Decision
/adr --status accepted Migrate from REST to GraphQL for Client API
Generates an ADR that supersedes a previous REST API decision, with rationale for the migration and updated consequence analysis.
Invoke with: /adr <title> then answer the prompts to capture your architectural decision