---
name: agileflow-adr
description: Detects architectural or technical decisions in conversations and formats them as Architecture Decision Records in docs/03-decisions/. Loads when discussing technology choices, architecture patterns, or trade-offs.
allowed-tools: Read, Write, Edit, Glob
---

# AgileFlow ADR (Architecture Decision Records)

## Purpose

This skill automatically captures architectural and technical decisions from conversations and formats them as formal Architecture Decision Records (ADRs) in `docs/03-decisions/`.

## When This Skill Activates

Load this skill when:
- Discussing technology choices ("Should we use PostgreSQL or MongoDB?")
- Debating architecture patterns ("REST vs GraphQL")
- Making framework decisions ("React vs Vue")
- Discussing infrastructure choices ("AWS vs GCP")
- Evaluating trade-offs between options
- User mentions "decision", "choose", "architecture", "trade-off"

## ADR Format (MADR - Markdown Architecture Decision Records)

```markdown
# [ADR-###] Title

**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Deprecated | Superseded
**Deciders**: Names of people involved
**Tags**: architecture, database, api, etc.

## Context and Problem Statement

[Describe the context and the problem that led to this decision.
What are we trying to solve? Why is this decision necessary?]

## Decision Drivers

- [Driver 1: e.g., Performance requirements]
- [Driver 2: e.g., Team expertise]
- [Driver 3: e.g., Cost constraints]

## Considered Options

- [Option 1]
- [Option 2]
- [Option 3]

## Decision Outcome

**Chosen option**: [Option X]

**Justification**: [Why was this option chosen? What makes it the best fit for our context?]

### Positive Consequences

- [Good outcome 1]
- [Good outcome 2]

### Negative Consequences

- [Bad outcome 1]
- [Bad outcome 2 - with mitigation plan if possible]

## Pros and Cons of the Options

### [Option 1]

**Pros**:
- [Pro 1]
- [Pro 2]

**Cons**:
- [Con 1]
- [Con 2]

### [Option 2]

**Pros**:
- [Pro 1]
- [Pro 2]

**Cons**:
- [Con 1]
- [Con 2]

### [Option 3]

**Pros**:
- [Pro 1]
- [Pro 2]

**Cons**:
- [Con 1]
- [Con 2]

## Links

- [Related ADRs]
- [Relevant documentation]
- [External resources]

## Notes

- [Additional information]
- [Implementation notes]
- [Review date if applicable]
```

## Workflow

1. **Detect decision discussion**: User is debating options or asking "which should we use?"

2. **Ask clarifying questions** if needed:
   - "What problem are you trying to solve?"
   - "What options are you considering?"
   - "What are your constraints (cost, time, expertise)?"

3. **Extract decision elements**:
   - Context/problem
   - Options being considered
   - Trade-offs for each option
   - Decision drivers (requirements, constraints)

4. **Read existing ADRs**:
   - Check `docs/03-decisions/` for numbering
   - Look for related decisions

5. **Generate ADR**:
   - Create file: `docs/03-decisions/ADR-###-descriptive-title.md`
   - Fill in all sections with gathered information
   - Mark status as "Proposed" unless decision is final

6. **Confirm with user**: Show the ADR and ask for corrections

## ADR Statuses

- **Proposed**: Under consideration, not yet decided
- **Accepted**: Decision made and approved
- **Deprecated**: No longer relevant (but kept for history)
- **Superseded**: Replaced by a newer decision (link to new ADR)

## Decision Drivers (Common Examples)

- **Performance requirements** (latency, throughput)
- **Scalability needs** (expected growth)
- **Team expertise** (learning curve)
- **Cost constraints** (budget, licensing)
- **Time to market** (urgency)
- **Maintenance burden** (long-term support)
- **Ecosystem maturity** (libraries, community)
- **Security requirements** (compliance, encryption)
- **Integration needs** (existing systems)

## Quality Checklist

Before creating ADR:
- [ ] Problem statement is clear and specific
- [ ] At least 2 options were considered
- [ ] Each option has pros and cons listed
- [ ] Decision drivers are explicitly stated
- [ ] Chosen option has clear justification
- [ ] Consequences (both positive and negative) are documented
- [ ] File name follows pattern: ADR-###-descriptive-title.md
- [ ] Status is appropriate (Proposed/Accepted)

## Examples

See `examples/` directory for well-formed ADRs across different domains.

## Tags (Common)

- `architecture` - Overall system design
- `database` - Data storage choices
- `api` - API design decisions
- `infrastructure` - Cloud, hosting, deployment
- `frontend` - UI framework, state management
- `backend` - Server framework, language
- `security` - Authentication, encryption
- `testing` - Test strategy, tools
- `cicd` - CI/CD pipeline choices
- `monitoring` - Observability tools

## Linking ADRs

When decisions build on or replace each other:

```markdown
## Links

- Supersedes [ADR-042: Use REST API](./ADR-042-use-rest-api.md)
- Related to [ADR-056: API Authentication](./ADR-056-api-authentication.md)
- Informs [ADR-073: Rate Limiting Strategy](./ADR-073-rate-limiting.md)
```

## Integration with Other Skills

- **agileflow-story-writer**: ADRs inform technical notes in stories
- **agileflow-tech-debt**: Negative consequences become tech debt items
- **agileflow-changelog**: Major decisions appear in changelog

## Updating ADRs

ADRs are immutable once accepted - don't edit them! Instead:
- Create a new ADR that supersedes the old one
- Update status to "Superseded by ADR-XXX"

## Notes

- Capture decisions even if they seem small - they provide context later
- Be honest about negative consequences - helps with future decisions
- Include who made the decision (deciders) - accountability matters
- Date decisions - context changes over time
- Keep ADRs focused - one decision per ADR