adr-writing

Original：🇺🇸 English

Translated

1 scripts

Write Architectural Decision Records following MADR template. Applies Definition of Done criteria, marks gaps for later completion. Use when generating ADR documents from extracted decisions.

2installs

Sourceexistential-birds/beagle

Added on2026-02-04

NPX Install

npx skill4agent add existential-birds/beagle adr-writing

SKILL.md Content

View Translation Comparison →

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

bash

python scripts/next_adr_number.py

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

).

For parallel allocation (used by parent commands):

bash

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:

markdown

* [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:

yaml

---
status: draft
date: YYYY-MM-DD
---

Full frontmatter template:

yaml

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