tomevault-io Architecture Decision Record (ADR) Skill
This skill provides guidelines for creating Architecture Decision Records - structured documentation of significant architectural decisions.
Purpose
ADRs capture important architectural decisions along with their context, alternatives considered, and consequences. They create a historical record of why things are built the way they are.
User Need
"Why did we decide to do it this way?"
Characteristics
| Attribute | Description |
|---|---|
| Orientation | Decision documentation |
| Focus | Context, decision, consequences |
| Goal | Record rationale for future reference |
| Tone | Objective, comprehensive |
Target Directory
Place ADRs in: docs/architecture/ with naming convention ADR-NNN-short-title.md
Writing Guidelines
DO
- State the context and problem clearly
- Document all alternatives considered
- Explain why alternatives were rejected
- List both benefits and drawbacks
- Include implementation notes
- Use consistent status labels
- Number ADRs sequentially
DON'T
- Skip the context section
- Omit alternatives that were considered
- Hide drawbacks of the chosen approach
- Forget to update status when decisions change
- Write ADRs for trivial decisions
When to Write an ADR
- Choosing between competing technologies
- Establishing patterns that will be reused
- Making breaking changes to existing systems
- Decisions that are costly to reverse
- Decisions that affect multiple teams or components
Examples of Good ADRs
- "ADR-001: Use PostgreSQL for primary database"
- "ADR-002: Adopt microservices architecture"
- "ADR-003: Implement event sourcing for audit log"
- "ADR-004: Choose React for frontend framework"
- "ADR-005: Use JWT for API authentication"
ADR Status Values
| Status | Meaning |
|---|---|
| Proposed | Under discussion, not yet decided |
| Accepted | Decision made and in effect |
| Deprecated | No longer applies, but kept for history |
| Superseded | Replaced by another ADR (link to it) |
Template
Use this template when creating an Architecture Decision Record:
# ADR-[Number]: [Short Title]
*Date: [YYYY-MM-DD]*
*Status: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]*
*Deciders: [List of people involved in the decision]*
## Context
[Describe the issue motivating this decision. What is the problem we're facing? What constraints exist? What forces are at play?]
[Include relevant technical, business, and organizational context.]
## Decision
[State the decision that was made. Use active voice: "We will..." or "The system will..."]
[Be specific about what changes will be made and what approach will be taken.]
## Consequences
### Benefits
- [Positive outcome 1]
- [Positive outcome 2]
- [Positive outcome 3]
### Drawbacks
- [Negative outcome or trade-off 1]
- [Negative outcome or trade-off 2]
### Risks
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How to address] |
## Alternatives Considered
### Alternative 1: [Name]
[Description of this alternative]
**Pros:**
- [Advantage]
**Cons:**
- [Disadvantage]
**Why rejected:** [Reason this wasn't chosen]
### Alternative 2: [Name]
[Description]
**Pros:**
- [Advantage]
**Cons:**
- [Disadvantage]
**Why rejected:** [Reason]
## Implementation Notes
[Any notes relevant to implementing this decision]
- [Implementation detail 1]
- [Implementation detail 2]
## References
- [Link to relevant documentation]
- [Link to discussion/RFC]
- [Link to related ADRs]
---
## Change Log
| Date | Author | Change |
|------|--------|--------|
| [Date] | [Name] | Initial draft |
Quality Checklist
Apply this checklist before finalizing any ADR.
Context
- Problem is clearly stated
- Constraints are documented
- Business and technical context included
- Scope is defined
Decision
- Decision is explicitly stated
- Active voice used ("We will...")
- Specific about what changes
- Approach is clear
Consequences
- Benefits are documented
- Drawbacks are honestly stated
- Risks are identified with mitigations
- Both short and long-term impacts considered
Alternatives
- Multiple alternatives considered
- Each alternative fairly evaluated
- Rejection reasons are clear
- Pros and cons for each
Metadata
- Status is current
- Date is accurate
- Deciders are listed
- ADR number is sequential
ADR-Specific
- Appropriate for an ADR (not trivial)
- Self-contained and understandable
- Links to related ADRs if any
- Implementation notes if needed
Maintainability
- References are linked
- Change log started
- Easy to update status later
- No broken links
Formatting
- Consistent heading structure
- Tables properly formatted
- Lists are clear
- Readable and scannable
Converted and distributed by TomeVault — claim your Tome and manage your conversions.