ADR Writer Agent

The ADR Writer Agent (ADR-WRITER) is your specialist in documenting architecture decisions, recording trade-offs, and maintaining a historical record of technical choices. This agent ensures that important decisions are captured with proper context so teams don't re-debate the same choices.

Capabilities

• ADR Creation: Create Architecture Decision Records documenting why technical choices were made
• Alternatives Documentation: Record 2-5 alternatives considered with pros/cons for each
• Trade-off Analysis: Document positive, negative, and neutral consequences of decisions
• Decision Linking: Connect related ADRs and reference supporting research
• Status Lifecycle: Track ADRs through Proposed → Accepted → Deprecated/Superseded states
• Research Integration: Coordinate with Research Agent for supporting technical analysis
• ADR Index Maintenance: Keep docs/03-decisions/README.md current with all decisions

When to Use

Use this agent when you need to document:

• Technology Choices: Framework selection, database choice, programming language, library decisions
• Architecture Patterns: Monolith vs microservices, REST vs GraphQL, event-driven vs request-response
• Data Modeling: Schema design, normalization strategy, caching approach
• Security Approaches: Authentication mechanism, encryption strategy, secrets management
• Infrastructure Decisions: Hosting platform, CI/CD system, monitoring solution
• Development Practices: Testing strategy, branching model, code style guidelines
• Performance Tradeoffs: When speed vs memory, or throughput vs latency decisions are made

How It Works

1. Context Loading: Agent reads expertise file, checks recent ADRs, and scans docs/10-research/ for supporting research

2. Understanding: Agent clarifies what decision is being made and why it's needed now

3. Research Integration: Agent checks for existing research on the decision topic, or requests research if needed via /agileflow:research:ask

4. Alternatives Analysis: Agent identifies 2-5 alternatives with pros/cons (from research or user input)

5. ADR Drafting: Agent creates ADR with:

   • Sequential 4-digit number (0001, 0002, etc.)
   • Title in imperative form ("Use PostgreSQL for data persistence")
   • Context explaining why decision is needed now
   • Decision statement (what was chosen)
   • Alternatives with pros/cons
   • Consequences (positive, negative, neutral)
   • Status (Proposed, Accepted, Deprecated, Superseded)
   • References linking to research notes and official docs

6. Preview & Approval: Agent shows preview for YES/NO approval

7. Creation: Agent creates docs/03-decisions/adr-<NUMBER>-<slug>.md

8. Indexing: Agent updates docs/03-decisions/README.md with new entry

Example

Copy# Via /babysit
/agileflow:babysit
> "We need to document why we chose PostgreSQL over MongoDB for our database"

The ADR Writer Agent would:

1. Check docs/10-research/ for existing database research
2. If missing, request: "Let me research database options first"
3. Gather research on PostgreSQL, MongoDB, other options
4. Interview you on context (why now? constraints? team experience?)
5. Draft ADR-0003: Use PostgreSQL for data persistence
6. Show preview with all alternatives and trade-offs
7. Get approval (YES/NO)
8. Create adr-0003-use-postgresql.md
9. Update docs/03-decisions/README.md
10. Announce: "ADR-0003 created and ready for team review"

Key Behaviors

• Research First: Always checks for existing research before writing ADR (or requests it)
• Context Over Implementation: Focuses on why decision was made, not implementation details
• Historical Record: Never deletes ADRs (kept for historical context and pattern recognition)
• Clear Alternatives: Documents at least 2 alternatives with honest pros/cons (no advocacy)
• Sequential Numbering: ADRs numbered sequentially (0001, 0002, 0003, etc.)
• Status Tracking: Updates ADR status as decisions evolve (Proposed → Accepted → Superseded)
• Linking: Connects related ADRs to build decision graph over time

Tools Available

This agent has access to:

• Read: Browse ADRs and understand decision history
• Write: Create new ADR files
• Edit: Update existing ADRs (change status, add references)
• Glob: Find ADRs by pattern
• Grep: Search decision content

ADR Template

Every ADR follows this structure:

Copy# ADR-<NUMBER>: <Title>
 
**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Deprecated | Superseded
**Deciders**: [Names/roles who made decision]
 
## Context
[Describe forces at play: technical, business, team, timeline]
[What problem are we solving? What constraints exist?]
 
## Decision
[State the decision clearly in 1-3 sentences]
[Explain key reasons for this choice]
 
## Alternatives Considered
 
### Option 1: [Name]
**Pros**:
- [Benefit]
- [Benefit]
 
**Cons**:
- [Cost or limitation]
- [Cost or limitation]
 
**Why rejected**: [Explanation]
 
### Option 2: [Name]
...
 
## Consequences
 
### Positive
- [Benefit we expect]
- [Advantage]
 
### Negative
- [Cost or limitation]
- [Trade-off]
 
### Neutral
- [Change that's neither good nor bad]
 
## References
- [Title](URL) - Description
- [Research Note](docs/10-research/YYYYMMDD-slug.md) - How research informed decision

ADR Status Lifecycle

• Proposed: Under review, not yet approved (discussion phase)
• Accepted: Approved and should be followed by team
• Deprecated: No longer recommended (but kept for history)
• Superseded: Replaced by newer ADR (link to replacement, e.g., "Supersedes ADR-0001")

Quality Checklist

Before creating ADR:

• Context clearly explains why decision is needed NOW
• At least 2 alternatives documented with pros/cons
• Decision statement is clear and specific
• Consequences are balanced (positive, negative, neutral)
• References included for key claims
• Status appropriate (Proposed for review, Accepted for finalized)
• Number is sequential (check latest ADR number)
• Research is cited if available

ADR Index Format

docs/03-decisions/README.md maintains a table of all ADRs (with newest first):

Copy| Number | Date       | Title                              | Status   |
|--------|------------|-----------------------------------|----------|
| 0005   | 2025-12-24 | Use PostgreSQL for data persistence | Accepted |
| 0004   | 2025-12-21 | Implement event-driven architecture | Accepted |
| 0003   | 2025-12-18 | Use TypeScript for all new code    | Accepted |
| 0002   | 2025-12-15 | REST API over GraphQL              | Accepted |
| 0001   | 2025-12-12 | Next.js for web framework          | Accepted |

Decision Categories

ADRs typically fall into these categories:

Technology Decisions

• Which framework to use
• Which database to choose
• Which programming language for new services
• Which library for specific functionality

Architecture Decisions

• Monolith vs microservices
• Synchronous vs asynchronous communication
• Event-driven vs request-response
• REST vs GraphQL API style

Data Design Decisions

• Schema normalization level
• Caching strategy
• Data retention policies
• Master-slave vs peer-to-peer replication

Security & Infrastructure

• Authentication mechanism (JWT, OAuth2, session-based)
• Encryption at rest and in transit
• Secrets management approach
• Deployment and hosting platform

Development Practices

• Testing strategy (unit, integration, E2E coverage)
• Git branching model (git-flow, trunk-based, etc.)
• Code review process
• CI/CD automation level

Updating & Linking ADRs

Marking as Deprecated:

Copy**Status**: Deprecated
 
This decision is no longer recommended because [reason].
See ADR-0005 for the current approach.

Marking as Superseded:

Copy**Status**: Superseded
 
Superseded by ADR-0005: [New Decision Title]
 
This decision was replaced because [reason].

Cross-referencing:

Copy## Related Decisions
- Builds on: ADR-0003 (Database choice)
- Related to: ADR-0002 (API design)
- Supersedes: ADR-0001 (Previous framework decision)

Research Integration

The ADR Writer Agent always:

1. Checks docs/10-research/ for existing research on the topic
2. If research missing, requests: /agileflow:research:ask TOPIC=<decision>
3. Incorporates research findings into Alternatives section
4. References research note in ADR "References" section
5. Links ADR back to research note for future reference

This ensures:

• Decisions are based on thorough analysis
• Research findings are preserved
• Other agents can find supporting evidence for decisions
• Consistency across decision documentation

Preventing Re-debate

ADRs prevent teams from re-debating the same decisions by:

• Capturing Context: Recording what was known when decision was made
• Documenting Constraints: Why certain options were impossible
• Recording Trade-offs: What was given up to gain other benefits
• Linking to Research: Pointing to technical analysis that informed choice
• Maintaining History: Showing how decisions evolved over time

When similar decision question arises:

1. Check docs/03-decisions/ for related ADRs
2. Review context and consequences
3. Decide if situation has changed (supersede if yes, refer to existing if no)

Related Agents

• research - Provides technical analysis before ADR creation
• documentation - References ADRs in architectural docs
• epic-planner - Plans features around established decisions
• mentor - Explains decisions to new team members
• babysit - Can request ADR creation for technical choices

Common Patterns

ADRs Enable Knowledge Transfer

• New team members understand past reasoning
• Prevents re-implementation of failed approaches
• Speeds up onboarding (read ADRs vs trial-and-error)

Decision Graph Over Time

• Decisions build on each other (ADR-0002 builds on ADR-0001)
• Some decisions supersede others (ADR-0003 supersedes ADR-0001)
• Form connected web of understanding

Evidence-Based Decisions

• Each ADR backed by research notes
• Cites official documentation, not opinions
• Includes benchmarks and trade-off analysis
• Enables confident decision-making