adr-capture

name

adr-capture

description

Capture Architecture Decision Records (ADRs) from .context/ plans, findings, and analyses. Extracts binding decisions into numbered ADRs under docs/ADR/, maintains a machine-readable index, and validates coverage. Use when creating or reviewing context files that contain decisions. DO NOT use for observational findings without decisions, retroactive documentation of long-settled decisions, or inline comments. Triggers: 'capture decision', 'create ADR', 'document decision', 'architectural decision', 'record decision as ADR', 'extract decisions', 'ADR review', 'index ADRs', 'check ADR coverage'.

ADR Capture

Capture Architecture Decision Records from .context/ analysis, findings, plans, and reviews. Automatically extract decisions, create numbered ADRs, and maintain the index.

Immutability rule: Immutability begins at acceptance, not creation. A proposed, unmerged ADR is a draft and may be edited freely in place. Once accepted, an ADR's title, body, and context fields are frozen and only status and superseded_by may change; to replace an accepted decision, supersede it — create a new ADR and mark the old one as superseded. See ADR-061.

Prerequisites

• A .context/ file (plan, finding, or analysis) containing a binding decision — a choice that affects future development direction, architecture, conventions, or processes
• The context-file skill to create the source .context/ file if it doesn't exist yet
• assets/schemas/adr-frontmatter.schema.json and assets/templates/adr-template.yaml for schema validation

Quick Start

# Regenerate ADR index after adding or updating ADRs
scripts/regenerate-adr-index.sh

# Check for decisions in context files that lack ADRs
scripts/check-undocumented-decisions.sh

ADR Location and Structure

ADRs live at docs/ADR/adr-NNN-kebab-case-title.md. See docs/ADR/index.yaml for the full list.

ADR Frontmatter Schema

Every ADR MUST start with frontmatter. Use the template at assets/templates/adr-template.yaml to bootstrap new files.

---
title: "ADR-NNN: Human-readable decision title"
status: proposed | accepted | deprecated | superseded
date: YYYY-MM-DD
superseded_by: "adr-NNN"     # only when status is "superseded"
context:
  - path: .context/findings/topic-YYYY-MM-DD.md
---

Field rules:

• title — Must start with ADR-NNN: prefix; wrap in quotes
• status — proposed until reviewed, accepted for active decisions, deprecated or SUPERSEDED when replaced
• date — Creation date in ISO format; do not update on edits
• superseded_by — Only when status: superseded; value is the replacement ADR name
• context — List of relative paths to .context/ files that motivated the decision; omit entirely if none

ADR Body Template

**Status:** Proposed
**Date:** YYYY-MM-DD

## Context

What is the issue motivating this decision or change?

## Decision

What is the change being proposed or implemented?

## Consequences

What becomes easier or more difficult because of this change?

When to Use

Create an ADR whenever a .context/ file or a review makes a binding decision — a choice that affects future direction, architecture, conventions, or processes. ALWAYS link the ADR to its source context file.

Context file section	Decision example	ADR warranted?
Finding > Recommended Action	"Adopt Option A (native Go eval runner)"	Yes
Plan > Steps	"Phase 1: split reporter into sub-packages"	Yes
Plan > Open Questions	"Use sqllite vs postgres" — after resolved	Yes
Finding > Summary	"Observational research with no action"	No

When NOT to Use

• Observational findings without decisions — record as findings, not ADRs
• Retroactive documentation of long-settled decisions — ADRs capture forward-looking choices
• Inline comments or ephemeral notes — not every observation needs a decision record

Workflow

1. When creating a context file that contains a decision, create the ADR in the same session
2. Use the template — link the context file in the context: frontmatter field
3. Run the index regeneration script after creating the ADR
4. Set status: proposed initially; promote to accepted after implementation starts
5. When a decision is superseded: set status: superseded and superseded_by on the old ADR; create a new ADR referencing the old one via context:
6. After a PR merges, run scripts/merge-status-sync.sh --dry-run <pr-number> to check whether the PR closes out any linked plan or ADR that's still ACTIVE/DRAFT/proposed. Single-phase plans directly or frontmatter-linked to the PR auto-flip to DONE via a branch + PR when run without --dry-run; multi-phase plans, ADRs, and file-touch-only links are always flagged for a human to confirm — see references/merge-status-sync.md.

Scripts

scripts/validate-adr-frontmatter.sh        # Validate ADR frontmatter against JSON schema
scripts/regenerate-adr-index.sh            # Scan docs/ADR/ and regenerate index.yaml
scripts/check-undocumented-decisions.sh    # Find decisions without ADR coverage
scripts/merge-status-sync.sh               # Detect and (optionally) apply post-merge plan/ADR status drift

Mindset

• Not every finding needs an ADR — only decisions that shape future work
• The context: frontmatter field links decisions to their evidence; always populate it
• status: proposed is the safe default; promote after implementation review
• ADRs are immutable once accepted — a proposed/unmerged ADR may still be edited in place; after acceptance only status and superseded_by may be updated, and superseding is the only way to replace the decision
• Consider marking status: superseded rather than deleting old ADRs; the historical record preserves context even for reversed decisions
• Use production-grade terminology: pitfall, gotcha, ALWAYS, NEVER, anti-pattern

Troubleshooting

Problem                                 | Solution
Index not updating after ADR creation   | Run scripts/regenerate-adr-index.sh
Pre-commit hook blocking                | Run scripts/validate-adr-frontmatter.sh
Decision not found in ADR index         | Check the ADR has context: and valid frontmatter

Anti-Patterns

NEVER create an ADR without linking the source context file. WHY: The context: field is the provenance chain — without it the decision is untethered from its evidence. BAD: Creating an ADR with no context: references for a decision from a review. GOOD: Always include context: with the relative path to the .context/ file.

NEVER edit or delete an accepted ADR (a proposed/unmerged one may still be refined in place). WHY: Accepted ADRs are immutable records. Editing an accepted ADR distorts history; deleting erases the rationale trail. BAD: Rewording the body of an accepted ADR to reflect new understanding. GOOD: Set status: superseded and superseded_by; create a new ADR.

NEVER reuse ADR numbers. WHY: ADR numbers are permanent identifiers — reusing a number erases the mapping. GOOD: Always increment to the next unused number.

NEVER skip creating an ADR when a .context/ file contains a clear decision. WHY: The decision will be invisible to agents reading the ADR index, causing re-debate. GOOD: Create both the plan and ADR in the same session.

References

Topic	Reference	When to Use
ADR frontmatter field rules, status lifecycle, and validation	ADR Frontmatter Schema	Validating or debugging ADR frontmatter errors
Step-by-step supersession workflow with examples	ADR Supersession	Reversing or replacing an existing decision via supersession
Post-merge plan/ADR status drift detection: signals, auto-flip rules, usage	Merge Status Sync	Checking or applying status drift after a PR merges