ADR Distillation: Formalize Living Architecture Decisions

Captures and formalizes enduring system architecture decisions into tracked, standardized Architecture Decision Records (ADRs). Bridges the gap between incremental, often disposable planning artifacts (planning/) and the long-term repository truth recorded under docs/decisions/.

Inspired by Michael Nygard's ADR format, Markdown Architectural Decision Records (MADR), and Martin Fowler's ADR guidance.

When to Use

• Pre-Implementation (Reconnaissance & Pre-Step): During plan-wave or task inception, to inspect active architectural decisions and resolve conflicts or explicit superseding intent before code is written.
• Post-Implementation (Wave Completion & Post-Step): After a wave completes or milestone is reached, to extract enduring architectural choices from grilling logs (EXECUTION_PLAN_N.md), runtime deviations (STATE_N.md), or git history before context compaction or plan cleanup.
• Repository History Mining (Scaffold-Free Mode): In projects without planning/ scaffolds, by clustering commit histories, diffs, and PR discussions across milestones to construct a retroactive architectural timeline.

---

The Heuristic Filter: Architecture vs. Transient Churn

ADRs must represent living, long-term system design rather than task checklists. Before minting an ADR, ensure the decision satisfies at least two criteria:

1. High Reversibility Cost: Changing or undoing this choice requires substantial multi-module refactoring or data migration (e.g., database selection, framework change, CLI dispatch paradigm).
2. Pattern-Setting: The decision establishes a precedent or convention that future waves and agents must adhere to (e.g., standardizing on YAML frontmatter, Node >=18 engine constraints, zero-network user installation).
3. Cross-Cutting Boundary: Affects multiple components, public APIs, shared data contracts, or repository boundaries.
4. Evaluated Trade-Offs: Consciously accepted specific downsides to gain strategic benefits (e.g., increased disk usage for offline availability).

What NOT to Record in an ADR:

• Checkbox completions from task micro-plans (tasks/N.W.id.todo.md).
• Targeted test run logs, failure counts, or execution times.
• Local refactoring of private helper functions or variable naming.
• Temporary worker model escalations (e.g., Haiku to Sonnet).

---

Operational Modes

Mode A: Planning Scaffold Mode (planning/ Artifacts)

Used when working within plan-wave and wave-orchestration:

1. Inputs:
   • planning/EXECUTION_PLAN_N.md: Phase 1 Goal & Scope, Phase 3 Grilling Decision Log.
   • planning/STATE_N.md: Deviations from approved plan, gotchas, unexpected edge cases.
   • planning/tasks/N.W.id.todo.md: Micro-plan structural discoveries.
2. Extraction:
   • Extract the problem context from Phase 1.
   • Extract options considered and chosen rationale from Phase 3 dated decision lines.
   • Incorporate unexpected runtime discoveries from STATE_N.md wave reports.

Mode B: Git History Mode (Scaffold-Free Mining)

Used in repositories that do not use incremental planning documents, or for retroactive documentation:

1. Inputs:
   • Commit history: git log --reverse --patch [rev-range]
   • Dependency manifests (package.json, Cargo.toml, go.mod, pyproject.toml).
   • PR discussion summaries and commit message bodies.
2. Extraction:
   • Cluster commits by architectural pivot points (new dependencies, structural reorganizations, interface changes).
   • Mine commit message bodies for the problem context and rationale.
   • Formulate ADR drafts based on the structural diffs.

---

Bidirectional Lifecycle: Pre-Step and Post-Step

1. Pre-Step: Reconnaissance & Resolution (plan-wave)

Before writing code or locking task DAGs:

1. Ingest Active Decisions: Read docs/decisions/README.md and inspect all records where status: Accepted.
2. Inject Constraints: Feed active ADR requirements directly into task specs as non-negotiable constraints.
3. Resolve Divergences Upfront: If the user's request conflicts with an active ADR, do not silently proceed. Grill the user:

   "ADR-[ID] specifies [Current Choice]. The proposed goal requires [New Choice]. Does this plan supersede ADR-[ID], or should we adapt the plan to comply with ADR-[ID]?"

4. Record Superseding Intent: If the user intends to supersede, document it in EXECUTION_PLAN_N.md so the post-step knows to update the link.

2. Post-Step: Distillation & Living Index Update (wave-orchestration)

After wave execution passes verification and before compaction:

1. Filter & Draft: Pass wave state and diffs through the Heuristic Filter.
2. Mint Sequential ADR: Create docs/decisions/NNNN-<kebab-case-title>.md.
3. Update Superseded Records:
   • In the newly created ADR: set supersedes: "[OLD-ID]".
   • In the prior ADR: set status: Superseded, superseded_by: "[NEW-ID]".
4. Update Index: Re-render the living catalog table in docs/decisions/README.md.
5. Commit: Ensure docs/decisions/ changes are committed to version control.

---

ADR Document Format

Records are stored in docs/decisions/NNNN-<slug>.md using standard YAML frontmatter and MADR-compatible sections:

---
id: "0002"
title: "Package Bundled Skills Directly Without Network Sync"
status: "Accepted" # Proposed | Accepted | Deprecated | Superseded
date: 2026-10-10
authors:
  - "Andrew G. Brown"
supersedes: "0001"
superseded_by: null
source_context: "EXECUTION_PLAN_2" # Wave plan ref, PR #, or commit SHA
---

# 2. Package Bundled Skills Directly Without Network Sync

## Context and Problem Statement
Users installing skills in agent environments frequently encounter network or permission issues when attempting git-clone based syncs from upstream repositories...

## Decision Drivers
* Zero external network requirement for standard end-users.
* Fast, offline agent startup and installation.
* Clear boundary between maintainer tooling and user distribution.

## Considered Options
1. On-demand git clone during `skills install`.
2. Bundling pre-materialized skills directly in `./skills` directory.
3. Fetching npm tarballs from a remote registry.

## Decision Outcome
Chosen option: "Bundling pre-materialized skills directly in `./skills` directory", because it guarantees immediate, offline availability and eliminates runtime git dependencies.

### Consequences
* **Positive**: Reliable offline installation; simplified CI validation.
* **Negative**: Repository size increases slightly due to bundled skill assets.

## Validation & Compliance
Validated via `scripts/validate-skills.js` and `npm run test:validate`.

---

Living Catalog Index (docs/decisions/README.md)

Maintain an at-a-glance status table representing the current state of system architecture:

# Architecture Decision Records

| ID | Title | Status | Date | Supersedes | Superseded By | Context |
|---|---|---|---|---|---|---|
| [0001](0001-git-sync-skills.md) | Sync skills via git clone | Superseded | 2026-09-18 | - | [0003](0003-package-bundled-skills.md) | Scaffold |
| [0002](0002-node-minimum-version.md) | Standardize on Node >=18 runtime | Accepted | 2026-09-20 | - | - | Baseline |
| [0003](0003-package-bundled-skills.md) | Package Bundled Skills Directly | Accepted | 2026-10-10 | [0001](0001-git-sync-skills.md) | - | Wave Plan 2 |