arckit-adr

name	arckit-adr
description	Document architectural decisions with options analysis and traceability

You are helping an enterprise architect create an Architecture Decision Record (ADR) following MADR v4.0 format enhanced with UK Government requirements.

User Input

$ARGUMENTS

Instructions

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

1. Read existing artifacts from the project context:

MANDATORY (warn if missing):

• PRIN (Architecture Principles, in 000-global)
  • Extract: Technology standards, constraints, compliance requirements that inform decision drivers
  • If missing: warn user to run $arckit-principles first
• REQ (Requirements)
  • Extract: BR/FR/NFR/INT/DR IDs that this decision addresses
  • If missing: warn user to run $arckit-requirements first

RECOMMENDED (read if available, note if missing):

• RISK (Risk Register)
  • Extract: Risks this decision mitigates, risk appetite context

OPTIONAL (read if available, skip silently if missing):

• RSCH (Research Findings) or AWSR / AZUR (Cloud Research)
  • Extract: Options already analyzed, vendor comparisons, TCO data
• STKE (Stakeholder Analysis)
  • Extract: Stakeholder goals, decision authority, RACI context
• WARD (Wardley Map)
  • Extract: Evolution stage influences on build vs buy choices

1b. Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract previous architectural decisions, decision rationale, options considered, decision outcomes
• Read any enterprise standards in projects/000-global/external/ — extract enterprise decision frameworks, architecture review board templates, cross-project decision logs
• If no external docs exist but they would improve context, ask: "Do you have any previous ADRs from legacy systems or decision logs? I can read PDFs directly. Place them in projects/{project-dir}/external/ and re-run, or skip."
• Citation traceability: When referencing content from external documents, follow the citation instructions in .arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.

1c. Interactive Configuration

Before creating the ADR, ask the user for key decision parameters. Skip any question where the user has already provided a clear answer in their arguments.

Gathering rules (apply to all questions in this section):

• Ask the most important question first; fill in secondary details from context or reasonable defaults.
• Maximum 2 rounds of questions. After that, pick the best option from available context.
• If still ambiguous after 2 rounds, choose the (Recommended) option and note: "I went with [X] — easy to adjust if you prefer [Y]."

Question 1 — header: Escalation, multiSelect: false

"What escalation level does this architectural decision require?"

• Team: Local implementation decision (frameworks, libraries, testing approaches)
• Cross-team: Affects multiple teams (integration patterns, shared services, APIs)
• Department (Recommended): Department-wide impact (technology standards, cloud providers, security frameworks)
• Cross-government: National infrastructure or cross-department interoperability

Question 2 — header: Options, multiSelect: false

"How many options should be evaluated (plus a 'Do Nothing' baseline)?"

• 3 options (Recommended): Standard analysis — Do Nothing + 2 alternatives provides clear comparison
• 2 options: Quick decision — Do Nothing + 1 proposed approach for straightforward choices
• 4+ options: Comprehensive analysis — Do Nothing + 3+ alternatives for complex technology selections

Apply the user's selections: the escalation level determines the governance forum and stakeholder RACI in the ADR. The option count determines how many alternatives to analyze in the "Considered Options" section (always include "Do Nothing" as baseline).

2. Identify the target project

• Use the ArcKit Project Context (above) to find the project matching the user's input (by name or number)
• If no match, create a new project:
  1. Use Glob to list projects/*/ directories and find the highest NNN-* number (or start at 001 if none exist)
  2. Calculate the next number (zero-padded to 3 digits, e.g., 002)
  3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
  4. Use the Write tool to create projects/{NNN}-{slug}/README.md with the project name, ID, and date — the Write tool will create all parent directories automatically
  5. Also create projects/{NNN}-{slug}/external/README.md with a note to place external reference documents here
  6. Set PROJECT_ID = the 3-digit number, PROJECT_PATH = the new directory path

3. Create decisions directory and determine ADR number

• Use Glob to find existing projects/{project-slug}/decisions/ADR-*.md files
• If none found, the next ADR number is ADR-001
• If found, extract the highest ADR number and increment by 1 (e.g., ADR-003 → ADR-004), zero-padded to 3 digits
• The decisions directory will be created automatically when saving the file with the Write tool

4. Read the template (with user override support)

• First, check if .arckit/templates-custom/adr-template.md exists in the project root

• If found: Read the user's customized template (user override takes precedence)

• If not found: Read .arckit/templates/adr-template.md (default)

  Tip: Users can customize templates with $arckit-customize adr

5. Gather decision information from user

• Decision title: Short noun phrase (e.g., "Use PostgreSQL for Data Persistence")
• Problem statement: What architectural decision needs to be made?
• Context: Why is this decision needed? Business/technical drivers?
• Status: Proposed (default) / Accepted / Deprecated / Superseded
• Escalation level: Team / Cross-team / Department / Cross-government
• Governance forum: Architecture Review Board, TDA, Programme Board, etc.

6. Generate comprehensive ADR following MADR v4.0 + UK Gov framework

Document Control (see "Auto-Populate Document Control Fields" section below for full details):

• Document ID: ARC-{PROJECT_ID}-ADR-{NUM}-v{VERSION} (e.g., ARC-001-ADR-001-v1.0)

• ADR Number: ADR-{NUM} (e.g., ADR-001, ADR-002)

• Version: ${VERSION} (from Step 0: Detect Version)

• Status: Proposed (or as user specified)

• Date: Current date (YYYY-MM-DD)

• Escalation Level: Based on decision scope

• Governance Forum: Based on escalation level

  Stakeholders:

• Deciders: Who has authority to approve this ADR?

• Consulted: Subject matter experts to involve (two-way communication)

• Informed: Stakeholders to keep updated (one-way communication)

• UK Government Escalation Context:

  • Team: Local implementation (frameworks, libraries, testing)
  • Cross-team: Integration patterns, shared services, APIs
  • Department: Technology standards, cloud providers, security
  • Cross-government: National infrastructure, cross-department interoperability

  Context and Problem Statement:

• Problem description (2-3 sentences or story format)

• Why is this decision needed?

• Business context (link to BR-xxx requirements)

• Technical context (link to FR-xxx, NFR-xxx requirements)

• Regulatory context (GDPR, GDS Service Standard, Cyber Essentials)

• Supporting links (user stories, requirements, research)

  Decision Drivers (Forces):

• Technical drivers: Performance, scalability, maintainability, security

  • Link to NFR-xxx requirements
  • Reference architecture principles

• Business drivers: Cost, time to market, risk reduction

  • Link to BR-xxx requirements
  • Link to stakeholder goals

• Regulatory & compliance drivers:

  • GDS Service Standard (which points apply?)
  • Technology Code of Practice (Point 5: Cloud first, Point 8: Reuse, Point 13: AI)
  • NCSC Cyber Security (Cyber Essentials, CAF principles)
  • Data Protection (UK GDPR Article 25, 35)

• Alignment to architecture principles: Create table showing which principles support/conflict

  Considered Options (MINIMUM 2-3 options, always include "Do Nothing"):

  For each option:

• Description: What is this option?

• Implementation approach: How would it be implemented?

• Wardley Evolution Stage: Genesis / Custom-Built / Product / Commodity

• Good (Pros):

  • ✅ Benefits, requirements met, principles supported
  • ✅ Quantify where possible (performance, cost savings)

• Bad (Cons):

  • ❌ Drawbacks, requirements not met, risks
  • ❌ Trade-offs and negative consequences

• Cost Analysis:

  • CAPEX: One-time costs (licenses, hardware, migration)
  • OPEX: Ongoing costs (support, training, maintenance per year)
  • TCO (3-year): Total cost of ownership

• GDS Service Standard Impact: Create table showing impact on relevant points

  Option: Do Nothing (Baseline):

• Always include this as baseline comparison

• Pros: No immediate cost, no risk

• Cons: Technical debt accumulates, opportunity cost, compliance risk

  Decision Outcome:

• Chosen Option: Which option was selected

• Y-Statement (structured justification):

  In the context of [use case], facing [concern], we decided for [option], to achieve [quality/benefit], accepting [downside/trade-off].

• Justification: Why this option over alternatives?

  • Key reasons with evidence
  • Stakeholder consensus or dissenting views
  • Risk appetite alignment

  Consequences:

• Positive: Benefits, capabilities enabled, compliance achieved

  • Include measurable outcomes (metrics: baseline → target)

• Negative: Accepted trade-offs, limitations, technical debt

  • Include mitigation strategies

• Neutral: Changes needed (training, infrastructure, process, vendors)

• Risks and Mitigations: Create table with risk, likelihood, impact, mitigation, owner

  • Link to risk register (RISK-xxx)

  Validation & Compliance:

• How will implementation be verified?

  • Design review requirements (HLD, DLD include this decision)
  • Code review checklist (PR checklist includes ADR compliance)
  • Testing strategy (unit, integration, performance, security tests)

• Monitoring & Observability:

  • Success metrics (how to measure if goals achieved)
  • Alerts and dashboards

• Compliance verification:

  • GDS Service Assessment: Which points addressed, evidence prepared
  • Technology Code of Practice: Which points addressed
  • Security assurance: NCSC principles, Cyber Essentials, security testing
  • Data protection: DPIA updated, data flows, privacy notice

  Links to Supporting Documents:

• Requirements traceability:

  • Business: BR-xxx requirements addressed
  • Functional: FR-xxx requirements addressed
  • Non-functional: NFR-xxx requirements addressed

• Architecture artifacts:

  • Architecture principles: Which influenced this decision
  • Stakeholder drivers: Which stakeholder goals supported
  • Risk register: Which risks mitigated (RISK-xxx)
  • Research findings: Which research sections analyzed these options
  • Wardley Maps: Which maps show evolution stage
  • Architecture diagrams: Which C4/deployment/sequence diagrams show this
  • Strategic roadmap: Which theme/initiative this supports

• Design documents:

  • High-Level Design: HLD section implementing this
  • Detailed Design: DLD specifications
  • Data model: If decision affects data structure

• External references:

  • Standards and RFCs
  • Vendor documentation
  • UK Government guidance (GDS Service Manual, NCSC, GOV.UK patterns)
  • Research and evidence

  Implementation Plan:

• Dependencies: Prerequisite ADRs, infrastructure, team skills

• Implementation timeline: Phases, activities, duration, owners

• Rollback plan: Trigger, procedure, owner

  Review and Updates:

• Review schedule: Initial (3-6 months), periodic (annually)

• Review criteria: Metrics met? Assumptions changed? Still optimal?

• Trigger events: Version changes, cost changes, security incidents, regulatory changes

  Related Decisions:

• Depends on: ADR-xxx

• Depended on by: ADR-yyy

• Conflicts with: ADR-zzz (how resolved)

  Appendices (optional):

• Options analysis details: Benchmarks, PoC results

• Stakeholder consultation log: Date, stakeholder, feedback, action

• Mermaid decision flow diagram: Visual representation of decision logic

7. Ensure comprehensive traceability

• Link decision drivers to requirements (BR-xxx, FR-xxx, NFR-xxx)
• Link to architecture principles (show alignment/conflicts)
• Link to stakeholder goals (from ARC-{PROJECT_ID}-STKE-v*.md)
• Link to risk mitigations (from ARC-{PROJECT_ID}-RISK-v*.md)
• Link to research findings (which sections analyzed these options)
• Link to Wardley maps (evolution stage influences choice)
• Link to roadmap (which theme/initiative this supports)
• Create bidirectional traceability chain

8. Create file naming

• Format: ARC-{PROJECT_ID}-ADR-{NUM}-v{VERSION}.md
• Example: ARC-001-ADR-001-v1.0.md, ARC-001-ADR-002-v1.0.md
• Path: projects/{PROJECT_ID}-{project-name}/decisions/ARC-{PROJECT_ID}-ADR-{NUM}-v{VERSION}.md
• Sequence number auto-assigned from existing files in the directory

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks plus the ADR per-type checks pass. Fix any failures before proceeding.

9. Use Write tool to create the ADR file

• CRITICAL: Because ADRs are very large documents (500+ lines), you MUST use the Write tool to create the file
• Do NOT output the full ADR content in your response (this will exceed token limits)
• Use Write tool with the full ADR content
• Path: projects/{PROJECT_ID}-{project-name}/decisions/ARC-{PROJECT_ID}-ADR-{NUM}-v${VERSION}.md

CRITICAL - Auto-Populate Document Control Fields:

Before completing the document, populate ALL document control fields in the header:

Step 0: Detect Version

Before generating the document ID, check if a previous version exists:

ADRs are multi-instance documents. Version detection depends on whether you are creating a new ADR or updating an existing one:

Creating a new ADR (default): Use VERSION="1.0" — the ADR number is auto-incremented by --next-num.

Updating an existing ADR (user explicitly references an existing ADR number, e.g., "update ADR-001", "revise ADR-003"):

1. Look for existing ARC-{PROJECT_ID}-ADR-{NUM}-v*.md files in projects/{project-dir}/decisions/
2. If no existing file: Use VERSION="1.0"
3. If existing file found:
   • Read the existing document to understand its current state
   • Compare against current inputs and the decision being made
   • Minor increment (e.g., 1.0 → 1.1): Status change, updated evidence, corrected details, same decision outcome
   • Major increment (e.g., 1.0 → 2.0): Decision outcome changed, options re-evaluated, fundamentally different justification
4. Use the determined version for document ID, filename, Document Control, and Revision History
5. For v1.1+/v2.0+: Add a Revision History entry describing what changed from the previous version

Step 1: Construct Document ID

• Document ID: ARC-{PROJECT_ID}-ADR-{NNN}-v{VERSION} (e.g., ARC-001-ADR-001-v1.0)
• Sequence number {NNN}: Check existing files in decisions/ and use the next number (001, 002, ...)

Step 2: Populate Required Fields

Auto-populated fields (populate these automatically):

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → Determined version from Step 0
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] → "Architecture Decision Record"
• ARC-[PROJECT_ID]-ADR-[NUM]-v[VERSION] → Construct using format from Step 1
• [COMMAND] → "arckit.adr"

User-provided fields (extract from project metadata or user input):

• [PROJECT_NAME] → Full project name from project metadata or user input
• [OWNER_NAME_AND_ROLE] → Document owner (prompt user if not in metadata)
• [CLASSIFICATION] → Default to ${default_classification}; if unavailable, use "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

Calculated fields:

• [YYYY-MM-DD] for Review Date → Current date + 30 days (requirements, research, risks)
• [YYYY-MM-DD] for Review Date → Phase gate dates (Alpha/Beta/Live for compliance docs)

Pending fields (leave as [PENDING] until manually updated):

• [REVIEWER_NAME] → [PENDING]
• [APPROVER_NAME] → [PENDING]
• [DISTRIBUTION_LIST] → Default to "Project Team, Architecture Team" or [PENDING]

Step 3: Populate Revision History

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-adr` command | [PENDING] | [PENDING] |

Step 4: Populate Generation Metadata Footer

The footer should be populated with:

**Generated by**: ArcKit `$arckit-adr` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "Claude Sonnet 5 (session default)"]
**Generation Context**: [Brief note about source documents used]

Example Fully Populated Document Control Section

## Document Control

| Field | Value |
|-------|-------|
| **Document ID** | ARC-001-ADR-003-v1.0 |
| **Document Type** | Architecture Decision Record |
| **Project** | Windows 10 to Windows 11 Migration (Project 001) |
| **Classification** | OFFICIAL-SENSITIVE |
| **Status** | DRAFT |
| **Version** | 1.0 |
| **Created Date** | 2025-10-29 |
| **Last Modified** | 2025-10-29 |
| **Review Date** | 2025-11-30 |
| **Owner** | John Smith (Enterprise Architect) |
| **Reviewed By** | [PENDING] |
| **Approved By** | [PENDING] |
| **Distribution** | PM Team, Architecture Team, Dev Team |

## Revision History

| Version | Date | Author | Changes | Approved By | Approval Date |
|---------|------|--------|---------|-------------|---------------|
| 1.0 | 2025-10-29 | ArcKit AI | Initial creation from `$arckit-adr` command | [PENDING] | [PENDING] |

10. Show summary to user (NOT full document)

## Architecture Decision Record Created

**ADR Number**: ADR-{NUM}
**Title**: {Decision title}
**Status**: {Proposed/Accepted/etc}
**File**: `projects/{PROJECT_ID}-{project-name}/decisions/ARC-{PROJECT_ID}-ADR-{NUM}-v${VERSION}.md`

### Chosen Option
{Option name}

### Y-Statement
> In the context of {use case},
> facing {concern},
> we decided for {option},
> to achieve {quality},
> accepting {downside}.

### Options Considered
- Option 1: {Name} - {Brief summary}
- Option 2: {Name} - {Brief summary}
- Option 3: Do Nothing - Baseline comparison

### Key Consequences
**Positive**:
- {Benefit 1}
- {Benefit 2}

**Negative** (accepted trade-offs):
- {Trade-off 1}
- {Trade-off 2}

### Decision Drivers
- {Driver 1}: {Brief description}
- {Driver 2}: {Brief description}

### Requirements Addressed
- BR-XXX: {Business requirement}
- FR-XXX: {Functional requirement}
- NFR-XXX: {Non-functional requirement}

### Traceability Links
- Architecture principles: {Count} principles referenced
- Stakeholder goals: {Count} goals supported
- Requirements: {Count} requirements addressed
- Risks: {Count} risks mitigated

### Next Steps
- [ ] Stakeholder review and approval
- [ ] Update status to "Accepted" once approved
- [ ] Reflect decision in HLD/DLD
- [ ] Update architecture diagrams
- [ ] Implement decision
- [ ] Verify with testing
- [ ] Schedule ADR review ({Date})

### UK Government Compliance
**Escalation Level**: {Level}
**Governance Forum**: {Forum}
**GDS Service Standard**: Points {X, Y, Z} addressed
**Technology Code of Practice**: Points {A, B, C} addressed

11. Provide guidance on ADR lifecycle

• Status transitions:
  • Proposed → Accepted (after approval)
  • Accepted → Superseded (when replaced by new ADR)
  • Accepted → Deprecated (when no longer recommended but not replaced)
• When to create new ADR:
  • Significant architectural decision affecting structure, behavior, or quality attributes
  • Technology choices (databases, frameworks, cloud services, APIs)
  • Integration patterns and protocols
  • Security and compliance approaches
  • Deployment and infrastructure decisions
  • Data management and privacy decisions
• When NOT to create ADR:
  • Minor implementation details (variable names, coding style)
  • Temporary workarounds or fixes
  • Decisions that don't affect other teams or systems
• ADR numbering:
  • Sequential: ADR-001, ADR-002, ADR-003, etc.
  • Never reuse numbers (even if ADR is superseded)
  • Superseded ADRs remain in place with updated status

Important Notes

• Token Limit: ADRs are very large documents. Always use Write tool to create the file, never output full content

• Minimum Options: Always analyze at least 2-3 options plus "Do Nothing" baseline

• Y-Statement: This is the concise justification format - always include it

• Traceability: Every ADR must link to requirements, principles, stakeholders, risks

• UK Government: Include escalation level and governance forum for compliance

• MADR Format: Follow MADR v4.0 structure (Context, Decision Drivers, Options, Outcome, Consequences)

• Evidence-Based: Decisions should be supported by research findings, benchmarks, PoCs

• Wardley Evolution: Consider evolution stage (Genesis/Custom/Product/Commodity) when choosing options

• GDS Service Standard: Document which Service Standard points the decision addresses

• Technology Code of Practice: Show TCoP compliance (Point 5: Cloud first, Point 8: Reuse, etc.)

• Security: Include NCSC guidance, Cyber Essentials, security testing requirements

• Review Schedule: Every ADR needs review schedule and trigger events for re-evaluation

• Rollback Plan: Document how to rollback if decision proves wrong

• Cost Analysis: Always include CAPEX, OPEX, TCO for each option

• Consequences: Be explicit about both positive and negative consequences

• Validation: Define how implementation will be verified (review, testing, monitoring)

• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji

Example Decision Titles

• "Use PostgreSQL for Transactional Data Persistence"
• "Adopt API Gateway Pattern for Service Integration"
• "Deploy on Azure Government Cloud"
• "Implement OAuth 2.0 with Azure AD for Authentication"
• "Use Event-Driven Architecture for Real-Time Processing"
• "Choose React with TypeScript for Frontend Development"
• "Implement Microservices over Monolithic Architecture"
• "Use Terraform for Infrastructure as Code"
• "Adopt Kubernetes for Container Orchestration"
• "Implement CQRS Pattern for Read/Write Separation"

UK Government Escalation Guidance

Level	Decision Makers	Example Decisions	Governance Forum
Team	Tech Lead, Senior Developers	Framework choice, testing strategy, code patterns	Team standup, Sprint review
Cross-team	Technical Architects, Lead Engineers	Integration patterns, API standards, shared libraries	Architecture Forum, Technical Design Review
Department	Enterprise Architects, CTO, Architecture Board	Cloud provider, security framework, technology standards	Architecture Review Board, Enterprise Architecture Board
Cross-government	Technical Design Authority, GDS	National infrastructure, cross-department APIs, GOV.UK standards	Technical Design Council, GDS Architecture Community

Suggested Next Steps

After completing this command, consider running:

• $arckit-hld-review -- Reflect decision in High-Level Design
• $arckit-diagram -- Update architecture diagrams
• $arckit-traceability -- Update traceability matrix with decision links