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)

• Then read .arckit/templates/_partials/RENDERING.md and resolve the <!-- DOC-CONTROL-HEADER --> marker in the template before writing. Do not hand-write the Document Control table: the partial RENDERING.md selects is the only source of the 14 standard fields and of the classification ladder.

  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)

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 → comes from the resolved Document Control header, not from a placeholder. _partials/RENDERING.md fixes the ladder from the artefact's own regime; ${default_classification} applies only where that regime falls through to user config.

Calculated fields:

• [YYYY-MM-DD] for Next Review Date → Current date + 30 days (requirements, research, risks)
• [YYYY-MM-DD] for Next 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 Rendered Header and Revision History

## Document Control

<!-- DOC-CONTROL-HEADER -->
<!-- Resolved at command-execution time per _partials/RENDERING.md. -->

## 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})


: {Level}
: {Forum}
: Points {X, Y, Z} addressed
: 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