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)

# [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:

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