Our review
This skill helps document significant technical decisions using structured Architecture Decision Record (ADR) templates and best practices.
Strengths
- Provides clear templates for different decision complexities.
- Enforces a review process with multiple engineers.
- Includes lifecycle management and maintenance guidance.
- Offers concrete examples and common mistakes to avoid.
Limitations
- Requires discipline to write ADRs before implementation.
- Not suitable for minor changes.
- May add overhead for small teams.
Use when making any significant technical decision that has long-term impact, such as adopting a new framework or changing an API design.
Do not use for routine maintenance, minor bug fixes, or configuration changes where the decision is already obvious.
Security analysis
SafeThis skill only provides documentation guidance and templates for Architecture Decision Records. It uses only the Read tool, does not execute any code or system commands, and has no potential for harm.
No concerns found
Examples
Create an ADR for choosing PostgreSQL as our primary database, outlining context, options considered, and consequences.Write an Architecture Decision Record for migrating our frontend codebase from JavaScript to TypeScript, including decision drivers and trade-offs.Review the ADR at docs/adr/0012-caching-strategy.md and suggest improvements based on standard ADR best practices.name: architecture-decision-records description: This skill should be used when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes. It provides ADR templates and best practices. allowed-tools: Read
Architecture Decision Records
Capture the context and rationale behind significant technical decisions using structured ADR formats.
When to Use This Skill
| Write ADR | Skip ADR | | -------------------------- | ---------------------- | | New framework adoption | Minor version upgrades | | Database technology choice | Bug fixes | | API design patterns | Implementation details | | Security architecture | Routine maintenance | | Integration patterns | Configuration changes |
Quick Start
- Copy the template:
cp docs/adr/template.md docs/adr/NNNN-your-title.md - Fill in: Context, Decision Drivers, Options, Decision, Consequences
- PR for review (2+ senior engineers)
- Update
docs/adr/README.mdindex after merge
Core Concepts
An Architecture Decision Record captures:
- Context: Why we needed to make a decision
- Decision: What we decided
- Consequences: What happens as a result
ADR Lifecycle
Proposed --> Accepted --> Deprecated --> Superseded
|
Rejected
Read reference/adr-lifecycle.md for status transitions, deprecation patterns, and review checklists.
Process
1. Choose a Template
Pick the format that fits the decision's complexity:
| Decision Complexity | Template | |---------------------|----------| | Simple tech selection | Y-Statement (one paragraph) | | Medium decision | Lightweight ADR (0.5-1 page) | | Significant architecture change | Standard MADR (1-2 pages) | | Retiring a decision | Deprecation ADR | | Major cross-team proposal | RFC Style (2-4 pages) |
Read reference/adr-templates.md for all template formats ready to copy-paste.
2. Write the ADR
- Start with context -- explain the problem before the solution
- List 2-3 real alternatives with honest pros/cons
- State the decision clearly
- Document both positive and negative consequences with specifics
3. Review and Approve
- Submit as PR with 2+ senior engineer reviewers
- Consult affected teams
- Assess security, cost, and reversibility implications
4. Maintain
- Update ADR index after acceptance
- Create implementation tickets
- Never edit accepted ADRs -- write new ones to supersede
Read reference/adr-examples.md for complete worked examples (PostgreSQL selection, TypeScript adoption, MongoDB deprecation, event sourcing RFC).
Minimal Template (Copy-Paste Starter)
# ADR-NNNN: [Title]
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX
## Context
[Why do we need to decide this? What's the problem?]
## Decision
We will [decision].
## Consequences
- **Good**: [benefits]
- **Bad**: [drawbacks]
- **Mitigations**: [how we'll address the bad]
Common Mistakes
| Mistake | Fix | |---------|-----| | Writing ADR after implementation | Write during design phase | | Listing only one option | Always include 2-3 real alternatives | | Vague consequences | Be specific: "Adds ~200ms latency to checkout" | | Editing accepted ADRs | Write new ADR that supersedes | | No decision drivers | List explicit criteria with priorities | | Missing rejected ADRs | Document rejected options too |
Directory Structure
docs/adr/
README.md # Index of all ADRs
template.md # Team's ADR template
0001-use-postgresql.md
0002-caching-strategy.md
Reference Files
| File | Contents |
|------|----------|
| reference/adr-templates.md | All formats: MADR, lightweight, Y-statement, deprecation, RFC |
| reference/adr-examples.md | Complete worked examples for each format |
| reference/adr-lifecycle.md | Status transitions, review checklists, automation with adr-tools |
Resources
Error Handling
Conflicting ADRs: When a new decision contradicts an existing ADR, create a superseding ADR that explicitly references and deprecates the old one.
Missing context: If the decision rationale is unclear or incomplete, flag it and request clarification before recording.
API Documentation Generator
Documentation
Automatically generates OpenAPI/Swagger API documentation.
Technical Writer
Documentation
Writes clear technical documentation following top style guides.
Pivot Decision Framework
Documentation
Documents a strategic pivot or persevere decision with evidence, analysis, and rationale. Use when evaluating whether to change direction on a product, feature, or strategy based on market feedback.