ADR Writing Overview
Generate Architectural Decision Records (ADRs) following the MADR template with systematic completeness checking.
Quick Reference ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ SEQUENCE │ ──▶ │ EXPLORE │ ──▶ │ FILL │ │ (get next │ │ (context, │ │ (template │ │ number) │ │ ADRs) │ │ sections) │ └─────────────┘ └──────────────┘ └─────────────┘ │ │ │ ▼ │ ┌─────────────┐ │ │ VERIFY │ │ │ (DoD │ └─────────────────────────────────│ checklist)│ └─────────────┘
When To Use Documenting architectural decisions from extracted requirements Converting meeting notes or discussions to formal ADRs Recording technical choices from PR discussions Creating decision records from design documents Workflow Step 1: Get Sequence Number
If a number was pre-assigned (e.g., when called from /beagle:write-adr with parallel writes):
Use the pre-assigned number directly Do NOT call the script - this prevents duplicate numbers in parallel execution
If no number was pre-assigned (standalone use):
python scripts/next_adr_number.py
This outputs the next available ADR number (e.g., 0003).
For parallel allocation (used by parent commands):
python scripts/next_adr_number.py --count 3
Outputs: 0003, 0004, 0005 (one per line)
Step 2: Explore Context
Before writing, gather additional context:
Related code - Find implementations affected by this decision Existing ADRs - Check docs/adrs/ for related or superseded decisions Discussion sources - PRs, issues, or documents referenced in decision Step 3: Load Template
Load references/madr-template.md for the official MADR structure.
Step 4: Fill Sections
Populate each section from your decision data:
Section Source Title Decision summary (imperative mood) Status Always draft initially Context Problem statement, constraints Decision Drivers Prioritized requirements Considered Options All viable alternatives Decision Outcome Chosen option with rationale Consequences Good, bad, neutral impacts Step 5: Apply Definition of Done
Load references/definition-of-done.md and verify E.C.A.D.R. criteria:
Explicit problem statement Comprehensive options analysis Actionable decision Documented consequences Reviewable by stakeholders Step 6: Mark Gaps
For sections that cannot be filled from available data, insert investigation prompts:
- [INVESTIGATE: Review PR #42 discussion for additional drivers]
- [INVESTIGATE: Confirm with security team on compliance requirements]
- [INVESTIGATE: Benchmark performance of Option 2 vs Option 3]
These prompts signal incomplete sections for later follow-up.
Step 7: Write File
IMPORTANT: Every ADR MUST start with YAML frontmatter.
The frontmatter block is REQUIRED and must include at minimum:
status: draft date: YYYY-MM-DD
Full frontmatter template:
status: draft date: 2024-01-15 decision-makers: [alice, bob] consulted: [] informed: []
Validation: Before writing the file, verify the content starts with --- followed by valid YAML frontmatter. If frontmatter is missing, add it before writing.
Save to docs/adrs/NNNN-slugified-title.md:
docs/adrs/0003-use-postgresql-for-user-data.md docs/adrs/0004-adopt-event-sourcing-pattern.md docs/adrs/0005-migrate-to-kubernetes.md
Step 8: Verify Frontmatter
After writing, confirm the file:
Starts with --- on the first line Contains status: draft (or other valid status) Contains date: YYYY-MM-DD with actual date Ends frontmatter with --- before the title File Naming Convention
Format: NNNN-slugified-title.md
Component Rule NNNN Zero-padded sequence number from script - Separator slugified-title Lowercase, hyphens, no special characters .md Markdown extension Reference Files references/madr-template.md - Official MADR template structure references/definition-of-done.md - E.C.A.D.R. quality criteria Output Example
status: draft date: 2024-01-15 decision-makers: [alice, bob]
Use PostgreSQL for User Data Storage
Context and Problem Statement
We need a database for user account data...
Decision Drivers
- Data integrity requirements
- Query flexibility needs
- [INVESTIGATE: Confirm scaling projections with infrastructure team]
Considered Options
- PostgreSQL
- MongoDB
- CockroachDB
Decision Outcome
Chosen option: PostgreSQL, because...
Consequences
Good
- ACID compliance ensures data integrity
Bad
- Requires more upfront schema design
Neutral
- Team has moderate PostgreSQL experience