Use when writing or formatting an ADR document using the MADR template, applying Definition of Done (E.C.A.D.R.) criteria, or verifying ADR completeness. Triggers on "write the ADR", "format as MADR", "check ADR quality", "mark gaps in ADR". Also triggers when a decision has been extracted and needs to become a document. Does NOT extract decisions from conversations (use adr-decision-extraction) or orchestrate the full extract-confirm-write workflow (use write-adr).
Use when writing or formatting an ADR document using the MADR template, applying Definition of Done (E.C.A.D.R.) criteria, or verifying ADR completeness. Triggers on "write the ADR", "format as MADR", "check ADR quality", "mark gaps in ADR". Also triggers when a decision has been extracted and needs to become a document. Does NOT extract decisions from conversations (use adr-decision-extraction) or orchestrate the full extract-confirm-write workflow (use write-adr).
ADR Writing
Overview
Generate Architectural Decision Records (ADRs) following the MADR template with systematic completeness checking.
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
Gates (objective pass conditions)
Advance to the next step only when the pass condition holds. These replace “I explored” / “I verified” with checkable artifacts.
After
Pass condition
Step 2
Pass: You have a written list (bullets in draft preamble, scratch notes, or the ADR body) of paths under you consulted for related/superseded ADRs, you explicitly record that is missing or empty after checking. you list repo path for related code with one-line reason.
≥0
docs/adrs/
or
docs/adrs/
And
≥1
or
N/A
Step 5
Pass: For each E, C, A, D, R in references/definition-of-done.md, the draft either meets that letter’s checklist or contains an [INVESTIGATE: …] marker scoped to that gap.
Step 7
Pass: The ADR file exists at docs/adrs/NNNN-slugified-title.md, and a read of the file shows line 1 is --- and frontmatter parses as YAML.
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):
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
Gate: Meet the Step 2 row in Gates (objective pass conditions) before Step 3.
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
Gate: Meet the Step 5 row in Gates (objective pass conditions) before Step 6 (use [INVESTIGATE: …] where data is missing).
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:
Validation: Before writing the file, verify the content starts with --- followed by valid YAML frontmatter. If frontmatter is missing, add it before writing.
Gate: After write, meet the Step 7 row in Gates (objective pass conditions) (file on disk, YAML frontmatter present).
---
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
