/ln-24-architecture-decision-recorder

name: ln-24-architecture-decision-recorder
description: "Records one architecture decision with alternatives, consequences and status; does not design the whole system."

Architecture Decision Recorder

**Goal:** Preserve the context, forces, alternatives, decision, and consequences of one architecturally significant choice in a compact durable record. Change only approved decision documentation; do not design the whole system, approve a decision silently, delete history, audit code, or implement the choice.

**Execution contract:** The checklist defines completion. Track each item internally as `PENDING`, `PROVEN` with evidence, `CLEARED` with evidence its condition is absent, or `UNPROVEN` with a gap; reading, delegation, or tool failure is not proof. Reconcile after each section. Before returning, resolve all `PENDING`, count only `PROVEN` and `CLEARED`, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

| Need | Preferred capability | Fallback | |---|---|---| | Existing decision convention | Repository search and direct document reads | Use the default path and compact format | | Decision drivers | Requirements, architecture artifacts, implementation evidence, and stakeholder statements | Mark unsupported drivers `UNKNOWN` | | Alternatives and external claims | Repository evidence plus current official sources | Mark time-sensitive claims `UNVERIFIED` | | Sequence and supersession | Existing filenames, indexes, and decision links | Return `BLOCKED` rather than reuse a number | | Document mutation | Minimal patch to one approved decision record and necessary supersession links | Return `BLOCKED` if authority or path is unclear |

One record captures one decision. If the request contains independent decisions with different drivers or lifecycles, split them only with explicit approval.

Artifact Rules

• Reuse the repository's established ADR convention when one exists.
• Otherwise use `docs/architecture/decisions/NNNN-<slug>.md` with the next unused monotonic number.
• Never renumber, delete, or rewrite the decision and rationale of historical records. Permit scoped status and supersession-link updates under the rules below; distinguish evolving proposed drafts from accepted history.
• Default a new record to `Proposed`.
• Use `Accepted` only after explicit confirmation from an authorized decision-maker.
• A proposed replacement links to the current decision without changing its effective status. Mark the old record `Superseded` and link both directions only after the replacement is explicitly accepted; preserve historical content.
• Keep the record short enough to review as a single decision.
• Preserve the rationale a future maintainer needs to reconsider it safely.
• Label retrospective records explicitly; do not imply that documentation created after implementation was prior approval.
• Separate evidence needed before acceptance from monitoring required after adoption.
• Prefer stable repository references over conversation, branch-local, or ephemeral links.

Checklist

1. Establish the Decision Contract

• [ ] Resolve the exact decision, scope, owner or deciders, affected system, and why the choice is architecturally significant.
• [ ] Read repository instructions, Git state, and existing decision conventions.
• [ ] Search for duplicate, conflicting, deprecated, or superseding decisions before allocating a new record.
• [ ] Confirm the request is one decision rather than a broad design or implementation plan.
• [ ] Resolve the approved status; default to `Proposed` when acceptance is not explicit.

2. Gather Context and Forces

• [ ] State the current context and problem in value-neutral language.
• [ ] Extract business drivers, quality attributes, constraints, assumptions, and decision horizon from available evidence.
• [ ] Identify affected boundaries, contracts, data, security, operations, cost, ownership, and migration implications.
• [ ] Separate present facts from forecasts and preferences.
• [ ] Record contradictions or missing evidence that could change the choice.

3. Evaluate Alternatives

• [ ] Include the status quo and the simplest credible option unless they are demonstrably infeasible.
• [ ] For an open choice, compare materially different credible alternatives; for retrospective records, include only evidenced historical options and mark missing rationale unknown.
• [ ] Compare options against the same drivers: correctness, quality targets, complexity, reversibility, cost, operations, team fit, and evolution.
• [ ] State why each rejected alternative loses in this context without claiming universal inferiority.
• [ ] Record sensitivity or review triggers that would make a rejected option preferable later.

4. Record the Decision

• [ ] Write title, status, date, deciders or owner, context, drivers, considered options, decision, consequences, validation, and review triggers.