/docs/guides/adr.md

Architecture Decision Record (ADR) Guide

Guide Origin: Official | ArcKit Version: [VERSION]

/arckit:adr produces MADR v4.0-compatible architecture decision records backed by governance metadata and UK Government escalation requirements.

---

Inputs

Artefact	Purpose
Requirements & principles	Provide evaluation criteria and constraints
Risk register	Ensures mitigations or accepts residual risk
HLD/DLD references	Supplies context diagrams and interfaces
Compliance artefacts	Link to TCoP, Secure by Design, AI Playbook evidence when impacted

---

Command

/arckit:adr Document architectural decision for <topic>, compare options A/B/C

Output: projects/<id>/decisions/ARC-<id>-ADR-001-v1.0.md (uses multi-instance numbering) plus optional summary table appended to decisions/index.md.

Auto-versioning: Creating a new ADR auto-increments the ADR number. Updating an existing ADR (e.g., "update ADR-001") auto-increments the version (minor for updated evidence, major for changed decision outcome) instead of overwriting.

---

MADR Structure

Section	Notes
Context & Problem Statement	State trigger, affected capabilities, and non-negotiables
Decision Drivers	Reference stakeholder goals, NFRs, and compliance mandates
Considered Options	Minimum of two options; include baseline / do-nothing
Pros & Cons	Map to decision drivers; cite evidence from research or pilots
Decision Outcome	Selected option, rationale, status (Proposed/Accepted/Rejected)
Consequences	Positive/negative impacts, follow-on tasks, re-evaluation date
Governance & Approvals	Record design authorities, CABs, risk owners, sign-off dates

---

Usage Pattern

1. Run /arckit:adr immediately after new insights from /arckit:research, /arckit:hld-review, or vendor clarifications.
2. Attach document IDs from /arckit:traceability so requirements coverage stays auditable.
3. Version ADRs in git; never overwrite history—open new ADRs when reversing prior choices.
4. Feed summaries into /arckit:story so programme leadership tracks pivotal decisions.

---

Review Checklist

• Decision ties directly to stakeholder drivers or requirements IDs.
• Risks and mitigations reference the risk register entry numbers.
• Compliance impacts call out required evidence (TCoP point, Secure by Design activity, ATRS field).
• Follow-on actions list named owners and due dates; backlog items reference /arckit:backlog.