ADR Writing

Overview

Generate Architectural Decision Records (ADRs) following the MADR template with systematic completeness checking.

Quick Reference

CODEBLOCK0

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):
CODEBLOCK1

This outputs the next available ADR number (e.g., 0003).

For parallel allocation (used by parent commands):
CODEBLOCK2

Step 2: Explore Context

Before writing, gather additional context:

1. 1. Related code - Find implementations affected by this decision
2. Existing ADRs - Check docs/adrs/ for related or superseded decisions
3. 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:

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:

CODEBLOCK3

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:
CODEBLOCK4

Full frontmatter template:
CODEBLOCK5

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:

CODEBLOCK6

Step 8: Verify Frontmatter

After writing, confirm the file:

1. 1. Starts with --- on the first line
2. Contains status: draft (or other valid status)
3. Contains date: YYYY-MM-DD with actual date
4. Ends frontmatter with --- before the title

File Naming Convention

Format: NNNN-slugified-title.md

Reference Files

• - references/madr-template.md - Official MADR template structure
• INLINECODE18 - E.C.A.D.R. quality criteria

Output Example

CODEBLOCK7