Generating ADRs Skill | Agent Skills

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:

| Type | Signals | Often Missed? | |------|---------|---------------| | Architecture | ASCII diagrams, "→", "async vs sync" | No | | Data Model | "Key Design Decision", schema diagrams | No | | API Design | "Internal API", auth patterns | Yes | | Technology | "Uses Redis", TTL values | No | | Integration | "Each X in own transaction", retry patterns | Yes | | Business Logic | "Before/After", "Once per X not Y" | No | | Reuse Patterns | "Hybrid approach", "Reuse existing" | Yes |

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

| Aspect | Correct | Incorrect | |--------|---------|-----------| | Location | <project>/adrs/ | <prd-folder>/adr/ | | Numbering | ADR-0001 (4 digits) | ADR-001 (3 digits) | | Consequences | Good, because... | Free-form text | | Frontmatter | Include status, date | None | | Options | At least 2 listed | Only chosen option |

Common Mistakes

| Mistake | Fix | |---------|-----| | Missing "Considered Options" | Always list 2+ options, even if one was obvious | | Free-form consequences | Use "Good/Bad/Neutral, because" format | | Missing reuse decisions | Check for "hybrid", "reuse", "thin wrapper" | | ADRs in PRD folder | Put at project level <project>/adrs/ | | 3-digit numbering | Use 4 digits: ADR-0001 | | Missing context | Explain WHY decision was needed, not just what |

Anti-Patterns

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

Agent Skills: Generating ADRs

Install this agent skill to your local

Skill Files