/adr
Create Architecture Decision Records through interactive conversation.
Usage
/adr # Start conversation /adr "database selection for coordinatr" # Provide topic
Output Location
ADRs live with code in spaces/ :
spaces/[project]/docs/project/adrs/ ├── ADR-001-database-choice.md ├── ADR-002-auth-strategy.md └── ADR-003-testing-strategy.md
Execution Flow
- Gather Context
Current architecture
Read: spaces/[project]/docs/project/architecture-overview.md
Existing ADRs
Glob: spaces/[project]/docs/project/adrs/ADR-*.md
Project context
Read: ideas/[project]/project-brief.md
Relevant research
Glob: resources/research/*.md
- Interactive Conversation
Ask one at a time:
-
What decision needs to be made?
-
Why is this decision needed now?
-
What options are you considering? (2-4 alternatives)
-
What are the constraints? (time, budget, skills)
-
What are the trade-offs for each?
-
Which option do you prefer and why?
- Research Support
If user unsure about options:
-
Check existing research in resources/research/
-
Suggest /research for deeper dive
-
Use WebSearch for current best practices
- Create ADR Document
ADR-###: [Decision Title]
Status: Accepted Date: YYYY-MM-DD Decision Makers: [who was involved]
Context
[Why this decision is needed]
Decision
We will use [chosen option] because [rationale].
Options Considered
Option 1: [Name]
Pros: ... Cons: ...
Option 2: [Name]
Pros: ... Cons: ...
Consequences
Positive
- What we gain
Negative
- What we lose
- Technical debt accepted
Risks
- Risk and mitigation
Related Decisions
- Links to related ADRs/specs
References
- Documentation links
When to Use
-
Technology/framework selection
-
Architecture patterns
-
Third-party service choices
-
Data modeling approaches
-
Cross-project standards
Not for: Implementation details, temporary decisions, already-decided standards
ADR Lifecycle
-
Accepted - Decision made, actively followed
-
Deprecated - No longer relevant
-
Superseded - Replaced by newer ADR
Workflow
/brief -> /research -> /adr -> /spec