arckit-architecture-change

name	arckit-architecture-change
description	Create architecture change request with impact assessment and ADM cycle re-entry

You are helping an enterprise architect create an Architecture Change Request for TOGAF Phase H (Architecture Change Management). This document captures change requests with full impact assessment across capability, application, technology, and governance domains, plus ADM cycle re-entry points.

User Input

$ARGUMENTS

Prerequisites: Read Architecture Artifacts

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.

RECOMMENDED (read if available, note if missing):

• BORD (Architecture Board Review) — Extract: Governance context, board decisions, approval precedents, change policy
  • If missing: note in assumptions that board context could not be validated
• BPCM (Business Capability Model) — Extract: Current capability landscape for impact assessment
  • If missing: note that capability impact assessment will be limited
• ADMP (ADM Preliminary) — Extract: Architecture framework, principles, governance structure
  • If missing: note that framework alignment could not be validated
• PRIN (Architecture Principles) — Extract: Principle compliance implications of the change
  • If missing: note that principle compliance could not be validated
• TRANS (Transition Architecture) — Extract: Current transition plans that may be affected
  • If missing: note that transition plan impact could not be assessed

Prerequisites 1b: Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract change management policies, existing change requests, migration plans, and architectural baselines
• Read any enterprise standards in projects/000-global/external/ — extract change management frameworks, governance procedures, compliance requirements
• If no external change docs found but they would improve the output, ask: "Do you have any existing change requests, board minutes, or change management policies? I can read PDFs and images 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., [ACHG-C1]) next to findings informed by source documents and populate the "External References" section in the template.

Instructions

1. Identify or Create Project

Identify the target project from the hook context. If the user specifies a project that doesn't exist yet, 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

2. Determine Change Request Number

Change requests are multi-instance documents (like ADRs). Find the next available number:

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

3. Read the Template (with user override support)

Read the template (with user override support):

• First, check if .arckit/templates-custom/architecture-change-template.md exists in the project root
• If found: Read the user's customised template (user override takes precedence)
• If not found: Read .arckit/templates/architecture-change-template.md (default)
• Then, read .arckit/templates/_partials/RENDERING.md and resolve the template's <!-- DOC-CONTROL-HEADER --> marker to the Document Control partial it selects, applying the ${organisation_name} and ${default_classification} substitutions. Remove the marker and its comment from the output — a rendered artefact must never contain either.

Tip: Users can customise templates with $arckit-customize architecture-change

4. Interactive Configuration

Before creating the change request, ask the user for key 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: Change Type, multiSelect: false

"What type of architecture change is this?"

• Evolutionary (Recommended): Incremental improvement to existing architecture — extends or enhances current capabilities without fundamental change
• Transformational: Fundamental change that restructures significant portions of the architecture — new capabilities, technology platforms, or operating models
• Corrective: Fix for architectural deficiencies, technical debt, or compliance failures — restores intended design

Question 2 — header: Priority, multiSelect: false

"What is the priority level of this change?"

• Critical: Must be implemented immediately — safety, security, or regulatory compliance
• High: Major business impact — core capability changes, significant investment
• Medium (Recommended): Standard change — enhancement or improvement within planned cycles
• Low: Minor refinement — low-risk, low-cost improvements

Question 3 — header: ADM Re-Entry, multiSelect: true

"Which ADM phases need to be re-entered for this change?"

• Phase A (Architecture Vision): Change affects overall vision or scope
• Phase B (Business Architecture): Change affects business processes or organisation
• Phase C (Information Systems): Change affects data or application architecture
• Phase D (Technology Architecture): Change affects technology infrastructure
• Phase E (Opportunities & Solutions): Change affects solution options or migrations
• Phase F (Migration Planning): Change affects migration sequencing
• Phase G (Implementation Governance): Change affects implementation oversight
• Phase H (Change Management): Change affects ongoing change control

Apply the user's selections to populate the Change Type, Priority, and ADM Re-Entry sections of the template.

5. Gather Change Information from Context

Read all available documents identified in the Prerequisites section. Build a mental model of:

• Current architecture baseline (from BPCM, ADMP, APP): What exists today
• Proposed change: What is being requested and why
• Impact scope: Which domains are affected (capability, application, technology, governance)
• Transition plans (from TRANS): What existing plans this change might affect
• Governance context (from BORD): Board precedent and approval thresholds

6. Generate Architecture Change Request

Create a comprehensive Architecture Change Request document following the template structure.

Document Control

• Document ID: ARC-{P}-ACHG-{NUM}-v{VERSION} (e.g., ARC-001-ACHG-001-v1.0)
• Change ID: ACHG-{NUM} (e.g., ACHG-001, ACHG-002)
• Version: 1.0 for new change requests
• Status: DRAFT
• Date: Current date (YYYY-MM-DD)

1. Change Request Header

• Change ID: Sequential ID (ACHG-001, ACHG-002, etc.)
• Change Type: Evolutionary / Transformational / Corrective
• Submitted By: Extract from context or prompt user
• Date: Current date
• Priority: Critical / High / Medium / Low

2. Rationale

Provide a clear statement of why this change is needed. Include:

• Business driver: Business objective or problem being addressed
• Technical driver: Architectural reason (performance, security, scalability, compliance)
• Regulatory driver: Compliance requirements (UK GDPR, NCSC, GDS Service Standard) if applicable
• Trigger: What initiated this change request (audit finding, strategic shift, technology obsolescence, stakeholder request)

3. Impact Assessment

Assess impact across at least four categories:

3.1 Capability Impact

• Which business capabilities are affected?
• Classification: Enhanced / Modified / New / Retired
• Maturity level changes (reference BPCM)

3.2 Application Impact

• Which applications are affected?
• Classification: Enhanced / Modified / Replaced / Retired
• Integration impact on connected applications

3.3 Technology Impact

• Which technology components are affected?
• Classification: Enhanced / Modified / Replaced / Retired
• Infrastructure and platform implications

3.4 Governance Impact

• Which governance areas are affected?
• Compliance, standards, principles alignment
• Policy and procedure changes required

4. Affected Artefacts

List all architecture artefacts that will need updates as a result of this change:

• Cross-reference to existing documents (BPCM, STRAT, APP, ADMP, etc.)
• Impact level per artefact: High / Medium / Low
• Action required: Update / No change / New section

5. ADM Re-Entry Point

Map which ADM phases need to be re-entered and the scope of re-entry for each:

• For each phase (A through H), indicate Yes/No for re-entry
• Describe the scope of re-work needed in that phase
• If no phases require re-entry, note that the change is contained within Phase H only

6. Cost/Benefit

Provide financial assessment:

• Implementation cost (CAPEX)
• Ongoing costs (OPEX)
• Expected benefit (quantified where possible)
• Payback period
• For UK Government: include TCoP alignment and G-Cloud/DOS cost considerations

7. Risk Assessment

Identify and assess risks associated with the change:

• Technical risks (implementation complexity, integration)
• Operational risks (service disruption, user impact)
• Compliance risks (regulatory non-compliance)
• Financial risks (cost overruns, benefit shortfall)
• Include likelihood, impact, and mitigation for each

8. Approval Workflow

Document the governance workflow:

• Submission → Assessment → Board Review → Approval → Implementation
• Owner for each stage
• Decision status (Pending/Approved/Rejected/Conditional)
• Include architecture board or programme board as appropriate

9. Traceability

Create traceability links:

• BORD → affected artefacts → ACHG links
• Cross-reference to architecture principles
• Link to strategic objectives
• Link to requirements being addressed
• Link to existing change requests (if related)

7. Quality Gate

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

ACHG-specific quality requirements:

• Change type is explicitly defined (Evolutionary/Transformational/Corrective)
• Impact assessment covers at least 4 categories (capability, application, technology, governance)
• ADM re-entry mapping is present for all phases
• Cost/benefit section is populated (even if estimates)
• Risk assessment table has at least 2 risks identified
• Approval workflow has all 5 stages (Submission → Assessment → Board Review → Approval → Implementation)

8. Write the Architecture Change Request File

IMPORTANT: The architecture change request document will be a substantial document (typically 200-400 lines). You MUST use the Write tool to create the file, NOT output the full content in chat.

Create the file at:

projects/{P}/changes/ARC-{P}-ACHG-{NUM}-v1.0.md

Use the Write tool with the complete content following the template structure.

Auto-Populate Document Control Fields:

• [PROJECT_ID] → Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] → Use "1.0" for new change requests
• [DATE] / [YYYY-MM-DD] → Current date in YYYY-MM-DD format
• [CHANGE_TYPE] → From user input (Evolutionary/Transformational/Corrective)
• [ACHG_NUM] → Next available number (001, 002, etc.)
• [COMMAND] → "arckit.architecture-change"

9. Show Summary to User

After writing the file, show a concise summary (NOT the full document):

## Architecture Change Request Created

**Change ID**: ACHG-{NUM}
**Document**: `projects/{P}/changes/ARC-{P}-ACHG-{NUM}-v1.0.md`
**Document ID**: ARC-{P}-ACHG-{NUM}-v1.0

### Change Overview
- **Type**: [Evolutionary/Transformational/Corrective]
- **Priority**: [Critical/High/Medium/Low]
- **Status**: DRAFT

### Impact Summary
| Domain | Level | Count |
|--------|-------|-------|
| Capability | [High/Med/Low] | [N] affected |
| Application | [High/Med/Low] | [N] affected |
| Technology | [High/Med/Low] | [N] affected |
| Governance | [High/Med/Low] | [N] affected |

### ADM Re-Entry
| Phase | Required | Scope |
|-------|----------|-------|
| Phase A | [Yes/No] | [Scope] |
| Phase B | [Yes/No] | [Scope] |
...

### Cost/Benefit
| Item | Amount |
|------|--------|
| Implementation Cost | [£X] |
| Expected Benefit | [£Y/year] |
| Payback Period | [Z months] |

### Risks Identified: [N]
1. **[Risk 1]**: [Description] — [Likelihood] × [Impact] = [Overall]
2. **[Risk 2]**: [Description] — [Likelihood] × [Impact] = [Overall]

### Approval Workflow
| Stage | Owner | Status |
|-------|-------|--------|
| Submission | [Requester] | ✅ Submitted |
| Assessment | [Architect] | [Pending] |
| Board Review | [Board] | [Pending] |
| Approval | [Board Chair] | [Pending] |
| Implementation | [Team] | [Pending] |

### Synthesised From
- [✅/⚠️] Architecture Board Review: ARC-{P}-BORD-v[N].md
- [✅/⚠️] Business Capability Model: ARC-{P}-BPCM-v[N].md
- [✅/⚠️] ADM Preliminary: ARC-{P}-ADMP-v[N].md
- [✅/⚠️] Architecture Principles: ARC-{P}-APP-v[N].md
- [✅/⚠️] Transition Architecture: ARC-{P}-TRANS-v[N].md

### Next Steps
1. Review change request with Architecture Board: `$arckit-architecture-board`
2. Update transition plan for approved changes: 
 Re-assess gaps after implementation: 
 Schedule ADM cycle re-entry if phases require re-work
 Update affected artefacts after approval


 [N] artefacts identified for impact review
 [N] ADM phases marked for re-entry
 [N] risks assessed
 Linked to BORD governance context

: 

Important Notes

1. Evidence-Based Assessment: Impact assessments must reference actual artefacts from the project context. Do not invent capabilities, applications, or technologies without source evidence.

2. Use Write Tool: The change request document is typically 200-400 lines. ALWAYS use the Write tool to create it. Never output the full content in chat.

3. Change Types:

   • Evolutionary: Incremental — extends existing architecture without structural change
   • Transformational: Structural — reorganises significant portions of the architecture
   • Corrective: Remedial — fixes architectural deficiencies or compliance failures

4. Impact Categories: All four categories (capability, application, technology, governance) must be assessed even if impact is "None" for some. This ensures comprehensive coverage.

5. ADM Re-Entry: Not every change requires full ADM cycle re-entry. Phase H is the most common entry point for evolutionary changes. Transformational changes often require re-entry to Phases A-D.

6. Multi-Instance Numbering: Change requests follow sequential numbering (ACHG-001, ACHG-002, etc.) similar to ADRs. Numbers are never reused — superseded or rejected changes retain their numbers.

7. Integration with Other Commands:

   • Architecture Change feeds into: $arckit-transition-architecture (update migration plans), $arckit-gap-analysis (re-assess after implementation)
   • Architecture Change is informed by: $arckit-architecture-board (governance context), BPCM (capability baseline), ADMP (framework)

8. Version Management: If a change request needs revision (e.g., after board feedback), create a new version (v1.1 for minor changes, v2.0 for significant changes) rather than overwriting.

9. Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 months, > £100,000) to prevent markdown renderers from interpreting them as HTML tags or emoji.

10. UK Government Context: For UK Government projects, align change management with:

• GDS Service Standard: Change governance and user impact assessment
• NCSC CAF: Security control updates for technology changes
• Technology Code of Practice: Reuse-first principle for technology changes
• Cross-Government Services: Impact on shared services (GOV.UK Pay, Notify, Design System)

Suggested Next Steps

After completing this command, consider running:

• $arckit-transition-architecture -- Update transition plan for approved changes
• $arckit-gap-analysis -- Re-assess gaps after change implementation