adr

What this skill does

# ADR Skill

Create Architecture Decision Records (1-3 pages) that document specific technology choices, architectural decisions, or framework selections — capturing the decision, alternatives considered, evaluation criteria, and trade-offs for future reference.

**Key principle**: All information comes from the user. The `Read` tool is only for reading user-provided context files (existing ADRs, RFCs, tickets) that the user explicitly shares.

## When to Use an ADR

- Choosing between competing technologies (PostgreSQL vs MongoDB, Kafka vs RabbitMQ)
- Making a significant architectural pivot or framework decision
- Documenting a decision that will be hard to reverse
- Preserving the rationale behind a past decision for future team members
- Any "why did we choose X?" question that deserves a permanent answer

## Workflow

### Phase 1: Gather Context

Parse what the user already provided. Extract:
- **The decision**: What was decided or needs to be decided?
- **Context**: What situation forced this decision?
- **Alternatives**: What options were in consideration?

**Only ask for what's genuinely missing.**

**Essential questions** (use `references/question-bank.md` patterns, ask only if not already provided):

1. **Decision**: "What is the specific decision being made or documented?"
2. **Context/drivers**: "What situation or requirements led to this decision? What constraints apply?"
3. **Alternatives** (MANDATORY minimum 2): "What other options did you consider? Walk me through each one."
4. **Decision criteria**: "How did you evaluate the options? What mattered most — performance, cost, team familiarity, vendor support?"
5. **Trade-offs**: "What are you gaining with this choice? What are you giving up?"
6. **Consequences**: "What changes because of this decision? Any downstream implications?"
7. **Reconsideration triggers** (optional): "Under what circumstances should this decision be revisited?"
8. **Related context** (optional): "Any previous ADRs or RFCs this relates to?"

**If user is still deciding** (not yet made the decision): Offer research via `agent:web-research-specialist` to gather comparison data before writing.

**Rich context** (accept at any point):
- Existing ADRs → use `Read` tool to load for consistency
- Benchmark data or vendor docs → incorporate key findings
- Pasted comparisons → extract decision criteria

### Phase 2: Generate & Iterate

Once sufficient context is gathered, generate the **complete ADR draft** using the template from `assets/templates/template.md`.

**Content generation rules:**
- Use section headings from `template.md` exactly
- The **Alternatives Considered** section requires at least 2 alternatives — never skip this
- Use a comparison table for decision criteria evaluation
- Write trade-offs honestly — acknowledge weaknesses of the chosen option
- State the decision in clear, unambiguous language ("We will use PostgreSQL for all transactional data storage")
- Do NOT include checkboxes, HTML comments, guidance questions, or quality criteria in output

**After presenting the full draft:**
1. Internally validate against `assets/templates/quality-checklist.md` — never show to user
2. Check that alternatives section has sufficient depth and honest trade-offs
3. Iterate based on feedback
4. Save in requested format

## Document Structure

Key sections (from `assets/templates/template.md`):

| Section | Purpose |
|---------|---------|
| Title & Metadata | Decision ID, date, status, authors |
| Context | Current situation, drivers, goals, non-goals |
| Decision | Clear statement of what was decided |
| Alternatives Considered | **MANDATORY** 2+ alternatives with pros/cons |
| Decision Criteria | Evaluation table or criteria breakdown |
| Trade-offs Analysis | What we gain, what we give up |
| Consequences | Positive, negative, and risk consequences |
| Implementation Plan | How the decision is being carried out |
| Validation | POC results, benchmarks, evidence |
| Related Decisions | Links to other ADRs |
| Reconsideration | Triggers and expiration conditions |
| References | External docs, benchmarks, comparisons |
| Approval | Sign-off section |

## Quality Principles

- **Alternatives are mandatory** — an ADR with only one option considered is not credible
- The decision statement must be unambiguous — future readers should have no doubt what was decided
- Trade-offs must be honest — acknowledge real weaknesses of the chosen approach
- Include the decision criteria explicitly — future readers need to understand what values drove the choice
- "Do nothing" / "status quo" is always a valid alternative to include

## Visual Aids

Comparison diagrams or architecture context diagrams can strengthen ADRs. When requested:
1. Ask what the diagram should show
2. Invoke `common-engineering:mermaid` skill
3. Integrate into relevant section

## Integration Points

| Capability | When to Use |
|-----------|-------------|
| `agent:web-research-specialist` | Compare technologies, gather benchmark data, research options |
| `common-engineering:mermaid` | Architecture context or comparison diagrams |
| `document-skills:docx` | Export to Word format |
| `document-skills:pdf` | Export to PDF format |

## Reference Files

| File | Purpose |
|------|---------|
| `references/writing-guidelines.md` | Technical writing best practices |
| `references/question-bank.md` | AskUserQuestion patterns for this skill |
| `assets/templates/template.md` | Document structure (use for output) |
| `assets/templates/guidance.md` | Section-by-section guidance (read, never copy to output) |
| `assets/templates/quality-checklist.md` | Internal validation (never show to user) |
| `assets/templates/examples.md` | Completed examples for quality reference |