# Adr

> Create Architecture Decision Records through interactive conversation. Use when making technology choices, architecture patterns, or third-party service selections.

- Skill: `diegosouzapw/adr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/adr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/adr/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/adr

---


# /adr

Create Architecture Decision Records through interactive conversation.

## Usage

```bash
/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

```bash
# 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

```markdown
# 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
```