/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

1. 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

2. Interactive Conversation

Ask one at a time:

1. What decision needs to be made?
2. Why is this decision needed now?
3. What options are you considering? (2-4 alternatives)
4. What are the constraints? (time, budget, skills)
5. What are the trade-offs for each?
6. Which option do you prefer and why?

3. Research Support

If user unsure about options:

• Check existing research in

  resources/research/

• Suggest

  /research

  for deeper dive
• Use WebSearch for current best practices

4. 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

1. Accepted - Decision made, actively followed
2. Deprecated - No longer relevant
3. Superseded - Replaced by newer ADR

Workflow

/brief -> /research -> /adr -> /spec