Adr Capture

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.

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