write-adr

Write ADR

Generate Architecture Decision Records (ADRs) from decisions made during the current session.

Workflow Overview

1. Context - Gather repository context and existing ADRs
2. Extract - Analyze conversation for decisions using a subagent
3. Confirm - Present decisions to user for selection
4. Write - Generate ADRs in parallel using subagents
5. Report - Summarize created files and status
6. Verify - Validate generated ADRs against Definition of Done

Gates (objective pass conditions)

Advance only when the pass condition holds. These are checkable without “I verified internally.”

After	Pass condition
Step 2 (extract)	The subagent response is valid JSON with a top-level decisions array (empty is OK). Each non-empty item has id, title, and at least one of context, decision, alternatives, or rationale present as a non-empty string or non-empty array. If parsing fails or the shape is wrong, re-run extraction or fix the payload before Step 3.
Step 4 (pre-allocate)	From repo root, python plugins/beagle-analysis/skills/adr-writing/scripts/next_adr_number.py --count N prints exactly N lines (one number per line). You have a written mapping (in the reply draft or notes) from each selected decision to one of those lines before launching any ADR writer unit.
Step 5 (report)	Every file path in the summary table is copied from a subagent completion output (not invented). Optionally spot-check: test -f <path> for each path before marking success.
Step 6 (verify)	For each ADR path, opening the file shows line 1 is ---, frontmatter parses as YAML, status and date are present, and the body meets the Step 6 bullets below (alternatives count, Good/Bad consequences).

Step 1: Gather Context

# Get current branch and recent commits
git branch --show-current
git log --oneline -5

# Check for existing ADRs
ls docs/adrs/ 2>/dev/null || echo "No ADR directory found"

# Count existing ADRs for numbering
find docs/adrs -name "*.md" 2>/dev/null | wc -l

This context helps the ADR writer:

• Reference related commits in the ADR
• Avoid duplicate ADRs for already-documented decisions
• Determine correct sequence numbering

Step 2: Extract Decisions

Analyze the current conversation for architectural decisions. If the agent supports subagents, dispatch this as a single extraction subagent; otherwise run the same extraction inline — identical output. Use this brief:

Load the **adr-decision-extraction** skill ([../adr-decision-extraction/SKILL.md](../adr-decision-extraction/SKILL.md)).

Analyze the conversation for decisions that warrant ADRs:
- Technology choices, architecture patterns, design trade-offs
- Rejected alternatives, significant implementation approaches

Return JSON:
{
  "decisions": [
    {
      "id": 1,
      "title": "Use PostgreSQL for primary datastore",
      "context": "Brief context about why this came up",
      "decision": "What was decided",
      "alternatives": ["What was considered but rejected"],
      "rationale": "Why this choice was made"
    }
  ]
}

If the subagent returns an empty decisions array, skip to Step 5 with message: "No architectural decisions detected in this session."

Gate: Meet the Step 2 row in Gates (objective pass conditions) before Step 3.

Step 3: Confirm with User

Display all extracted decisions with full details, then ask user to select:

## Detected Decisions

### 1. Use PostgreSQL for primary datastore
**Confidence:** high

**Problem:** Need ACID transactions for financial records

**Decision:** PostgreSQL for user data storage

**Alternatives discussed:**
- MongoDB
- SQLite

**Rationale:** ACID compliance, team familiarity, mature ecosystem

**Source:** Discussion about database selection in planning phase

---

### 2. Implement event sourcing for audit trail
**Confidence:** medium

**Problem:** Compliance requires complete audit history

**Decision:** Event sourcing pattern for state changes

**Alternatives discussed:**
- Database triggers
- Application-level logging

**Rationale:** Immutable audit trail, temporal queries, debugging capability

**Source:** Compliance requirements discussion

---

## Selection

Which decisions should I write ADRs for?
- Enter numbers (e.g., "1,2" or "1-2"), "all", or "none" to skip

Important: Always display the full decision details (problem, decision, alternatives, rationale) from the extraction output BEFORE asking for selection. Do not truncate to just title and context.

Parse user response:

• "all" - Process all decisions
• "none" or empty - Skip with message "No ADRs will be created."
• "1,2" or "1-2" - Process specified decisions

Step 4: Write ADRs (Parallel)

Pre-allocate ADR numbers before launching subagents to prevent numbering conflicts:

# Pre-allocate numbers for all confirmed decisions (from repository root)
# Example: If user selected 3 decisions
python plugins/beagle-analysis/skills/adr-writing/scripts/next_adr_number.py --count 3
# Output:
# 0003
# 0004
# 0005

Assign each pre-allocated number to its corresponding decision before launching subagents.

Gate: Meet the Step 4 row in Gates (objective pass conditions) before launching the first ADR writer unit.

For each confirmed decision, run an ADR writer unit with its pre-assigned number. If the agent supports subagents, dispatch one writer per decision in parallel; otherwise write each ADR sequentially — identical output. Use this brief:

Load the **adr-writing** skill ([../adr-writing/SKILL.md](../adr-writing/SKILL.md)).

Write an ADR for this decision:
```json
{decision JSON}

IMPORTANT: Use this pre-assigned ADR number: {assigned_number}

Instructions:

1. Explore codebase for additional context
2. Write MADR-formatted ADR to docs/adrs/
3. Use the pre-assigned number {assigned_number} - DO NOT call next_adr_number.py
4. Filename format: {assigned_number}-slugified-title.md
5. Return created file path

**Critical:** Pass the pre-allocated number to each writer unit. Writers must NOT call `next_adr_number.py` themselves - this causes duplicate numbers when running in parallel.

Wait for all writer units to complete before proceeding.

## Step 5: Report Results

**Gate:** Meet the Step 5 row in **Gates (objective pass conditions)** when building the summary (paths from subagent outputs; optional `test -f`).

Collect outputs from all subagents and present summary:

```markdown
## ADR Generation Complete

| File | Decision | Status |
|------|----------|--------|
| docs/adrs/0003-use-postgresql.md | Use PostgreSQL for primary datastore | Draft |

### Next Steps
- Review generated ADRs for accuracy
- Update status from "proposed" to "accepted" when finalized

### Gaps Requiring Investigation
- [List any decisions where subagent noted missing context]

If no decisions were processed:

No ADRs were created. Run this command again after making architectural decisions.

Step 6: Verify Generated ADRs

For each created ADR, validate against Definition of Done:

## Verification Checklist

| ADR | E | C | A | D | R | Status |
|-----|---|---|---|---|---|--------|
| 0003-use-postgresql.md | ✓ | ✓ | ✓ | ⚠ | ✗ | Incomplete |

Legend: E=Evidence, C=Criteria, A=Agreement, D=Documentation, R=Realization

Gate: Meet the Step 6 row in Gates (objective pass conditions) for every created ADR.

Verification steps:

1. Open each generated ADR file
2. Confirm filename follows NNNN-slugified-title.md pattern
3. Verify YAML frontmatter exists at file start:
   • File MUST begin with ---
   • Contains status: draft (or valid status)
   • Contains date: YYYY-MM-DD (actual date)
   • Ends with --- before title
   • If frontmatter is missing, add it immediately
4. Review for [INVESTIGATE] prompts - these need follow-up
5. Verify at least 2 alternatives are documented
6. Confirm consequences section has both Good and Bad items

If gaps exist:

• Keep status as draft until gaps are resolved
• Use [INVESTIGATE] prompts to guide follow-up session
• Schedule review with stakeholders before changing to accepted

Output Location

ADRs are written to docs/adrs/ (same convention as adr-writing). If no ADR directory exists, create it with an initial 0000-use-madr.md template record.

MADR Format Reference

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

# {TITLE}

## Context and Problem Statement

{What is the issue motivating this decision?}

## Decision Drivers

* {driver 1}
* {driver 2}

## Decision Outcome

Chosen option: "{option}", because {reason}.

### Consequences

* Good, because {positive}
* Bad, because {negative}