Generating ADRs

Extract architectural decisions from PRDs/TRDs and generate MADR (Markdown Any Decision Record) format ADR documents.

When to Use

• PRD/TRD contains architectural choices to document
• User asks to "document decisions" or "create ADRs"
• Retrospectively capturing decisions from existing requirements
• Before implementation to formalize choices
• After implementation to document what was decided and why

When NOT to Use

• Simple bug fixes with no architectural impact
• Requirements without design decisions
• Already-documented decisions (check existing ADRs first)

Workflow

Phase 0: Locate PRD and Existing ADRs

Step 1: Find the source PRD/TRD

Read the PRD directory or file provided by user.

Step 2: Check for existing ADRs

# Look for existing ADR directory at project level
ls -la <project>/adrs/ <project>/docs/adrs/ 2>/dev/null

If ADRs exist, determine next sequence number. If not, start at 0001.

Step 3: Determine output location

ADRs go in <project>/adrs/ directory (project level, NOT inside PRD folder).

Example: PRD at /Works/tada/bridge/agent-workflow/requirements/ → ADRs at /Works/tada/bridge/adrs/

Phase 1: Identify Decision Points

Scan PRD for decision patterns. See references/decision-patterns.md for full taxonomy.

Decision Types to Extract:

Critical: Check for commonly missed decisions:

• Reuse vs build-new decisions ("hybrid approach", "thin wrapper")
• Error isolation patterns ("each config in own transaction")
• Internal vs external API decisions
• Calculation context decisions (what value is used as base)

Phase 2: Determine ADR Scope

For each decision, assess if it warrants own ADR:

Create separate ADR when:

• Affects multiple components
• Involves documented trade-offs
• May be questioned later
• Sets precedent for future work

Combine into single ADR when:

• Decisions tightly coupled
• Same rationale drives multiple choices
• From "Confirmed Decisions" table (can group)

Skip ADR when:

• Implementation detail only
• Standard practice with no alternatives
• Single-component impact

Phase 3: Generate ADRs

Use MADR format from references/madr-template.md.

Required sections (baseline test showed these are often missing):

---
status: accepted
date: YYYY-MM-DD
---

# ADR-NNNN: Title

## Status
{proposed | accepted | deprecated | superseded by ADR-XXXX}

## Context and Problem Statement
{WHY was this decision needed - 2-3 sentences}

## Decision Drivers
- {Driver 1}
- {Driver 2}

## Considered Options
1. {Option 1}
2. {Option 2}

## Decision Outcome
Chosen option: "{Option X}", because {justification}.

### Consequences
- Good, because {positive impact}
- Bad, because {negative impact}
- Neutral, because {neutral impact}

Consequence format is critical - always use:

• Good, because {specific positive}
• Bad, because {specific negative}
• Neutral, because {neither positive nor negative}

Phase 4: Create Index

Generate adrs/README.md:

# Architecture Decision Records

| ID | Title | Status | Date |
|----|-------|--------|------|
| [ADR-0001](ADR-0001-decision-title.md) | Decision Title | Accepted | YYYY-MM-DD |
| [ADR-0002](ADR-0002-another-decision.md) | Another Decision | Accepted | YYYY-MM-DD |

Phase 5: Save Output

Directory structure:

<project>/adrs/
    README.md                              # Index
    ADR-0001-first-decision.md
    ADR-0002-second-decision.md

Naming convention:

• 4-digit sequence: ADR-0001 not ADR-001
• Kebab-case: ADR-0001-use-async-queue.md
• Title in file: # ADR-0001: Use Async Queue

Quick Reference

Common Mistakes

Anti-Patterns

1. Missing alternatives - Always document what was NOT chosen
2. Vague context - Be specific about forces and constraints
3. No negative consequences - Every decision has trade-offs
4. Wrong location - ADRs at project level, not inside PRD
5. Skipping reuse decisions - "Hybrid approach" is architectural

See Also

• references/madr-template.md - Full and minimal templates
• references/decision-patterns.md - How to identify decisions
• references/extraction-examples.md - PRD → ADR transformations