ln-74-architecture-decision-recorder
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 ordered checkboxes are the Definition of Done. Track every item internally as PENDING, PROVEN with concrete evidence, CLEARED with evidence that its condition is absent, or UNPROVEN with a gap; reading, delegation, or tool failure is not proof. Reconcile items after each section. Before returning, resolve all PENDING and count only PROVEN and CLEARED; apply the skill's verdict and approval rules to every gap.
Preserve user intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without silently skipping checks. Preserve dependency and safety ordering; otherwise choose the verification method appropriate to each obligation.
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.