arckit-analyze

---
name: arckit-analyze
description: "Perform comprehensive governance quality analysis across architecture artifacts (requirements, principles, designs, assessments)"
---

## User Input

```text
$ARGUMENTS
```

## Goal

Identify inconsistencies, gaps, ambiguities, and compliance issues across all architecture governance artifacts before implementation or procurement. This command performs **non-destructive analysis** and produces a structured report saved to the project directory for tracking and audit purposes.

## Operating Constraints

**Non-Destructive Analysis**: Do **not** modify existing artifacts. Generate a comprehensive analysis report and save it to the project directory for tracking, sharing, and audit trail.

**Architecture Principles Authority**: The architecture principles (`ARC-000-PRIN-*.md` in `projects/000-global/`) are **non-negotiable**. Any conflicts with principles are automatically CRITICAL and require adjustment of requirements, designs, or vendor proposals—not dilution or reinterpretation of the principles.

**UK Government Compliance Authority** (if applicable): TCoP, AI Playbook, and ATRS compliance are mandatory for UK government projects. Non-compliance is CRITICAL.

## Execution Steps

### 0. Read the Template

**Read the template** (with user override support):

- **First**, check if `.arckit/templates/analysis-report-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/analysis-report-template.md` (default)

> **Tip**: Users can customize templates with `$arckit-customize analyze`

### Hook-Aware Shortcut

If the hook has injected a `## Governance Scan Pre-processor Complete` section in the context, follow this protocol. If no hook data is present, proceed with Steps 1-2 as normal.

**Rule 1 — Hook tables are primary data.** Use them directly for all detection passes. Do NOT re-read any artifact file listed in the Artifact Inventory table.

**Rule 2 — Targeted reads only.** When a detection pass needs evidence beyond hook tables, use Grep (search for specific patterns) or Read with offset/limit (specific sections). NEVER read an entire artifact file.

**Rule 3 — Skip Steps 1-2 entirely.** Go directly to Step 3. Still read the template (Step 0) for output formatting.

#### Hook Data to Detection Pass Mapping

Use this table to identify the primary data source for each detection pass. Only perform a targeted read when the hook data is genuinely insufficient for a specific check.

| Detection Pass | Primary Hook Data | Targeted Read (only if needed) |
|---|---|---|
| A. Requirements Quality | Requirements Inventory, Priority Distribution, Placeholder Counts | Hook data sufficient for all Pass A checks |
| B. Principles Alignment | Principles table + Requirements Inventory | Grep PRIN files for full validation criteria of specific principles flagged as violated |
| C. Req-Design Traceability | Coverage Summary, Orphan Requirements, Cross-Reference Map | Hook data sufficient for all Pass C checks |
| D. Vendor Procurement | Vendor Inventory + Cross-Reference Map | Grep vendor HLD/DLD for specific requirement IDs missing from cross-ref map |
| E. Stakeholder Traceability | Artifact Inventory (STKE presence) + Requirements Inventory | Grep STKE for driver-goal-outcome chains when validating orphan requirements |
| F. Risk Management | Risks table + Requirements Inventory | Grep RISK file for "Risk Appetite" section only (appetite thresholds) |
| G. Business Case | Artifact Inventory (SOBC presence) + Risks table | Grep SOBC for benefits table and option analysis section |
| H. Data Model Consistency | Requirements Inventory (DR-xxx) + Cross-Reference Map | Grep DATA file for entity catalog when validating DR-entity mapping |
| I. UK Gov Compliance | Compliance Artifact Presence | Grep TCOP for per-point scores; Grep AIPB for risk level and principle status |
| J. MOD SbD Compliance | Compliance Artifact Presence | Grep SECD-MOD for SbD principle scores and NIST CSF function scores |
| K. Cross-Artifact Consistency | All hook tables (Document Control, coverage, cross-refs) | Hook data sufficient for all Pass K checks |

#### Targeted Read Examples

Correct (surgical):

- `Grep "Risk Appetite" in projects/001-*/ARC-*-RISK-*.md` then read only 10-20 lines around match
- `Grep "### 5\. Cloud" in projects/000-global/ARC-000-PRIN-*.md` to get one principle's full criteria
- `Read ARC-001-TCOP-v1.0.md offset=50 limit=30` to get just the scoring table

Wrong (wasteful — this data is already in hook tables):

- `Read ARC-001-REQ-v1.0.md` — entire requirements file (use Requirements Inventory table)
- `Read ARC-001-RISK-v1.0.md` — entire risk register (use Risks table)
- `Read ARC-000-PRIN-v1.0.md` — entire principles file (use Principles table, grep only for specific criteria)

### 1. Discover Project Context

Identify the project directory to analyze:

- If user specifies project: Use specified project directory
- If only one project exists: Analyze that project
- If multiple projects: Ask user which project to analyze

Expected structure:

```text
projects/
└── {project-dir}/
    ├── ARC-{PROJECT_ID}-STKE-v*.md (RECOMMENDED - stakeholder analysis)
    ├── ARC-{PROJECT_ID}-RISK-v*.md (RECOMMENDED - risk register)
    ├── ARC-{PROJECT_ID}-SOBC-v*.md (RECOMMENDED - business case)
    ├── ARC-{PROJECT_ID}-REQ-v*.md (requirements)
    ├── ARC-{PROJECT_ID}-DATA-v*.md (if DR-xxx requirements exist - data model)
    ├── ARC-*-SOW-*.md (if vendor procurement)
    ├── ARC-*-EVAL-*.md (if vendor procurement)
    ├── vendors/
    │   └── {vendor-name}/
    │       ├── hld-v1.md
    │       ├── dld-v1.md
    │       └── reviews/
    ├── ARC-*-TCOP-*.md (if UK Gov)
    ├── ARC-*-AIPB-*.md (if UK Gov AI)
    ├── ARC-*-ATRS-*.md (if UK Gov AI)
    ├── ARC-*-SECD-MOD-*.md (if MOD project)
    └── ARC-{PROJECT_ID}-TRAC-v*.md (traceability matrix)
```

### 2. Load Artifacts (Progressive Disclosure)

Load only minimal necessary context from each artifact:

**From any `ARC-000-PRIN-*.md` file in `projects/000-global/`** (if exists):

- Strategic principles (Cloud-First, API-First, etc.)
- Security principles
- Data principles
- Technology standards
- Compliance requirements

**From any `ARC-*-STKE-*.md` file in `projects/{project-dir}/`** (if exists):

- Stakeholder roster with power-interest grid
- Driver types (STRATEGIC, OPERATIONAL, FINANCIAL, COMPLIANCE, PERSONAL, RISK, CUSTOMER)
- Driver → Goal → Outcome traceability
- Conflicts and resolutions
- RACI matrix for governance

**From any `ARC-*-RISK-*.md` file in `projects/{project-dir}/`** (if exists):

- Risk categories (Strategic, Operational, Financial, Compliance, Reputational, Technology)
- Inherent vs Residual risk scores (5×5 matrix)
- Risk responses (4Ts: Tolerate, Treat, Transfer, Terminate)
- Risk owners (should align with RACI matrix)
- Risk appetite and tolerance levels

**From any `ARC-*-SOBC-*.md` file in `projects/{project-dir}/`** (if exists):

- Strategic Case (problem, drivers, stakeholder goals)
- Economic Case (options, benefits, NPV, ROI)
- Commercial Case (procurement strategy)
- Financial Case (budget, TCO)
- Management Case (governance, delivery, change, risks, benefits realization)

**From any `ARC-*-REQ-*.md` file in `projects/{project-dir}/`** (if exists):

- Business requirements (BR-xxx)
- Functional requirements (FR-xxx)
- Non-functional requirements (NFR-xxx)
  - Security (NFR-S-xxx)
  - Performance (NFR-P-xxx)
  - Compliance (NFR-C-xxx)
  - Accessibility (NFR-A-xxx)
- Integration requirements (INT-xxx)
- Data requirements (DR-xxx)
- Success criteria

**From any `ARC-*-DATA-*.md` file in `projects/{project-dir}/`** (if exists):

- Entity-Relationship Diagram (ERD)
- Entity catalog (E-001, E-002, etc.)
- PII identification and GDPR compliance
- Data governance matrix (owners, stewards, custodians)
- CRUD matrix (component access patterns)
- Data integration mapping (upstream/downstream)
- DR-xxx requirement traceability to entities

**From `projects/{project-dir}/ARC-*-SOW-*.md`** (if exists):

- Scope of work
- Deliverables
- Technical requirements
- Timeline and budget

**From `projects/{project-dir}/vendors/{vendor}/hld-v*.md`** (if exists):

- Architecture overview
- Component design
- Technology stack
- Security architecture
- Data architecture

**From `projects/{project-dir}/vendors/{vendor}/dld-v*.md`** (if exists):

- Component specifications
- API contracts
- Database schemas
- Security implementation

**From UK Government Assessments** (if exist):

- `ARC-*-TCOP-*.md`: TCoP compliance status
- `ARC-*-AIPB-*.md`: AI Playbook compliance status
- `ARC-*-ATRS-*.md`: ATRS record completeness

**From MOD Assessment** (if exists):

- `ARC-*-SECD-MOD-*.md`: MOD SbD compliance status
  - 7 SbD Principles assessment
  - NIST CSF (Identify, Protect, Detect, Respond, Recover)
  - CAAT registration and self-assessment completion
  - Three Lines of Defence
  - Delivery Team Security Lead (DTSL) appointment
  - Supplier attestation (for vendor-delivered systems)

### 3. Build Semantic Models

Create internal representations (do not include raw artifacts in output):

**Stakeholder Traceability Matrix** (if ARC-*-STKE-*.md exists):

- Each stakeholder with drivers, goals, outcomes
- RACI roles for governance
- Conflicts and resolutions
- Which requirements trace to which stakeholder goals?

**Risk Coverage Matrix** (if ARC-*-RISK-*.md exists):

- Each risk with category, inherent/residual scores, response
- Risk owners from RACI matrix
- Which requirements address risk mitigation?
- Which design elements mitigate risks?

**Business Case Alignment Matrix** (if ARC-*-SOBC-*.md exists):

- Benefits mapping to stakeholder goals
- Benefits mapping to requirements
- Costs mapping to requirements scope
- Risks from risk register reflected in Management Case

**Requirements Inventory**:

- Each requirement with ID, type, priority (MUST/SHOULD/MAY)
- Map to principles (which principles does this requirement satisfy?)
- Map to stakeholder goals (which goals does this requirement address?)
- Map to success criteria

**Data Model Coverage Matrix** (if ARC-*-DATA-*.md exists):

- Each DR-xxx requirement mapped to entities
- Each entity with PII flags, governance owners, CRUD access
- Data owners from stakeholder RACI matrix
- Database schema in DLD matches data model entities

**Principles Compliance Matrix**:

- Each principle with validation criteria
- Which requirements/designs satisfy each principle?

**Design Coverage Matrix**:

- Which requirements are addressed in HLD/DLD?
- Which components implement which requirements?

**UK Government Compliance Matrix** (if applicable):

- TCoP: 13 points with compliance status
- AI Playbook: 10 principles + 6 themes with compliance status
- ATRS: Mandatory fields completion status

**MOD Compliance Matrix** (if ARC-*-SECD-MOD-*.md exists):

- 7 SbD Principles with compliance status
- NIST CSF functions (Identify, Protect, Detect, Respond, Recover)
- CAAT registration status
- Three Lines of Defence implementation

### 4. Detection Passes (Token-Efficient Analysis)

Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.

#### A. Requirements Quality Analysis

**Duplication Detection**:

- Near-duplicate requirements across BR/FR/NFR categories
- Redundant requirements that should be consolidated

**Ambiguity Detection**:

- Vague adjectives lacking measurable criteria ("fast", "secure", "scalable", "intuitive")
- Missing acceptance criteria for functional requirements
- Unresolved placeholders (TODO, TBD, TBC, ???, `<placeholder>`)

**Underspecification**:

- Requirements with verbs but missing measurable outcomes
- Missing non-functional requirements (no security, no performance, no compliance)
- Missing data requirements (system handles sensitive data but no DR-xxx)
- Missing integration requirements (integrates with external systems but no INT-xxx)

**Priority Issues**:

- All requirements marked as MUST (no prioritization)
- No MUST requirements (everything is optional)
- Conflicting priorities

#### B. Architecture Principles Alignment

**Principle Violations** (CRITICAL):

- Requirements or designs that violate architecture principles
- Technology choices that conflict with approved stack
- Security approaches that violate security-by-design principle
- Cloud architecture that violates Cloud-First principle

**Missing Principle Coverage**:

- Principles not reflected in requirements
- Principles not validated in design reviews

**Principle Drift**:

- Inconsistent interpretation of principles across artifacts

#### C. Requirements → Design Traceability

**Coverage Gaps**:

- Requirements with zero design coverage (not addressed in HLD/DLD)
- Critical MUST requirements not covered
- Security requirements (NFR-S-xxx) not reflected in security architecture
- Performance requirements (NFR-P-xxx) not validated in design
- Compliance requirements (NFR-C-xxx) not addressed

**Orphan Design Elements**:

- Components in HLD/DLD not mapped to any requirement
- Technology choices not justified by requirements
- Architecture complexity not justified by requirements

**Traceability Completeness**:

- Does traceability matrix exist?
- Are all requirements mapped?
- Are all design elements mapped?

#### D. Vendor Procurement Analysis (if applicable)

**SOW Quality**:

- SOW requirements match ARC-*-REQ-*.md?
- All technical requirements from ARC-*-REQ-*.md included in SOW?
- Missing evaluation criteria?
- Ambiguous acceptance criteria?

**Vendor Evaluation**:

- Evaluation criteria align with requirements priorities?
- Scoring methodology fair and unbiased?
- All critical requirements included in evaluation?

**Vendor Design Review**:

- HLD addresses all SOW requirements?
- Technology stack matches approved standards?
- Security architecture meets NFR-S requirements?
- Performance architecture meets NFR-P requirements?

#### E. Stakeholder Traceability Analysis (if ARC-*-STKE-*.md exists)

**Stakeholder Coverage**:

- All requirements traced to stakeholder goals?
- Orphan requirements (not linked to any stakeholder goal)?
- Requirements missing stakeholder justification?

**Conflict Resolution**:

- Requirement conflicts documented and resolved?
- Stakeholder impact of conflict resolutions documented?
- Decision authority identified for conflicting requirements?

**RACI Governance Alignment**:

- Risk owners from stakeholder RACI matrix?
- Data owners from stakeholder RACI matrix?
- Delivery roles aligned with RACI assignments?

**Missing Stakeholder Analysis**:

- Project has requirements but no stakeholder analysis document (RECOMMENDED to run `$arckit-stakeholders`)

#### F. Risk Management Analysis (if ARC-*-RISK-*.md exists)

**Risk Coverage**:

- High/Very High inherent risks have mitigation requirements?
- Risks reflected in design (risk mitigation controls in HLD/DLD)?
- Risk owners assigned and aligned with RACI matrix?
- Risk responses appropriate (4Ts: Tolerate, Treat, Transfer, Terminate)?

**Risk-SOBC Alignment** (if ARC-*-SOBC-*.md exists):

- Strategic risks reflected in Strategic Case urgency?
- Financial risks reflected in Economic Case cost contingency?
- Risks from risk register included in Management Case Part E?

**Risk-Requirements Alignment**:

- Risk mitigation actions translated into requirements?
- Security risks addressed by NFR-S-xxx requirements?
- Compliance risks addressed by NFR-C-xxx requirements?

**Missing Risk Assessment**:

- Project has requirements but no risk register document (RECOMMENDED to run `$arckit-risk`)

#### G. Business Case Alignment (if ARC-*-SOBC-*.md exists)

**Benefits Traceability**:

- All benefits in Economic Case mapped to stakeholder goals?
- All benefits supported by requirements?
- Benefits measurable and verifiable?
- Benefits realization plan in Management Case?

**Option Analysis Quality**:

- Do Nothing baseline included?
- Options analysis covers build vs buy?
- Recommended option justified by requirements scope?
- Costs realistic for requirements complexity?

**SOBC-Requirements Alignment**:

- Strategic Case drivers reflected in requirements?
- Economic Case benefits delivered by requirements?
- Financial Case budget adequate for requirements scope?
- Management Case delivery plan realistic for requirements?

**SOBC-Risk Alignment**:

- Risks from risk register included in Management Case?
- Cost contingency reflects financial risks?
- Strategic risks justify urgency ("Why Now?")?

**Missing Business Case**:

- Project has requirements but no SOBC (RECOMMENDED for major investments to run `$arckit-sobc`)

#### H. Data Model Consistency (if ARC-*-DATA-*.md exists)

**DR-xxx Requirements Coverage**:

- All DR-xxx requirements mapped to entities?
- All entities traced back to DR-xxx requirements?
- Missing data requirements (system handles data but no DR-xxx)?

**Data Model-Design Alignment**:

- Database schemas in DLD match data model entities?
- CRUD matrix aligns with component design in HLD?
- Data integration flows in HLD match data model upstream/downstream mappings?

**Data Governance Alignment**:

- Data owners from stakeholder RACI matrix?
- Data stewards and custodians assigned?
- PII identified and GDPR compliance documented?

**Data Model Quality**:

- ERD exists and renderable (Mermaid syntax)?
- Entities have complete attribute specifications?
- Relationships properly defined (cardinality, foreign keys)?
- Data quality metrics defined and measurable?

**Missing Data Model**:

- Project has DR-xxx requirements but no data model (RECOMMENDED to run `$arckit-data-model`)

#### I. UK Government Compliance (if applicable)

**Technology Code of Practice (TCoP)**:

- Assessment exists?
- All 13 points assessed?
- Critical issues resolved?
- Evidence provided for each point?

**AI Playbook** (for AI systems):

- Assessment exists for AI/ML systems?
- Risk level determined (High/Medium/Low)?
- All 10 principles assessed?
- All 6 ethical themes assessed?
- Mandatory assessments completed (DPIA, EqIA, Human Rights)?
- Bias testing completed?
- Human oversight model defined?

**ATRS** (for AI systems):

- ATRS record exists for algorithmic tools?
- Tier 1 (public summary) completed?
- Tier 2 (technical details) completed?
- All mandatory fields filled?
- Ready for GOV.UK publication?

**Compliance Alignment**:

- Requirements aligned with TCoP?
- Design complies with TCoP (Cloud First, Open Standards, Secure)?
- AI requirements comply with AI Playbook?
- ATRS record reflects requirements and design?

#### J. MOD Secure by Design Compliance (if ARC-*-SECD-MOD-*.md exists)

**7 SbD Principles Assessment**:

- Principle 1 (Understand and Define Context): Context documented, data classification determined?
- Principle 2 (Apply Security from the Start): Security embedded from inception, not bolt-on?
- Principle 3 (Apply Defence in Depth): Layered security controls implemented?
- Principle 4 (Follow Secure Design Patterns): NCSC/NIST guidance applied?
- Principle 5 (Continuously Manage Risk): Risk register maintained, continuous testing?
- Principle 6 (Secure the Supply Chain): SBOM maintained, supplier attestations obtained?
- Principle 7 (Enable Through-Life Assurance): Continuous monitoring, incident response capability?

**NIST Cybersecurity Framework Coverage**:

- **Identify**: Asset inventory, business environment, governance, risk assessment?
- **Protect**: Access control, data security, protective technology, training?
- **Detect**: Continuous monitoring, anomaly detection, security testing?
- **Respond**: Incident response plan, communications to MOD CERT, analysis?
- **Recover**: Recovery planning, backup/DR/BC, post-incident improvements?

**Continuous Assurance Process** (replaced RMADS August 2023):

- CAAT (Cyber Activity and Assurance Tracker) registration completed?
- CAAT self-assessment question sets completed based on 7 SbD Principles?
- CAAT continuously updated (not one-time submission)?
- Delivery Team Security Lead (DTSL) appointed?
- Security Assurance Coordinator (SAC) appointed (if applicable)?
- Project Security Officer (PSyO) appointed for SECRET+ systems?

**Three Lines of Defence Implementation**:

- **First Line**: Delivery team owns security, DTSL leads day-to-day management?
- **Second Line**: Technical Coherence assurance, security policies, independent reviews?
- **Third Line**: Independent audit, penetration testing, external audit (NAO, GIAA)?

**Supplier Attestation** (if vendor-delivered system):

- Suppliers attest systems are secure (ISN 2023/10)?
- Supplier-owned continuous assurance (not MOD accreditation)?
- Supplier security requirements in contracts?

**Classification-Specific Requirements**:

- OFFICIAL: Cyber Essentials baseline, basic access controls?
- OFFICIAL-SENSITIVE: Cyber Essentials Plus, MFA, enhanced logging, DPIA?
- SECRET: SC personnel, CESG crypto, air-gap/assured network, enhanced physical security?
- TOP SECRET: DV personnel, compartmented security, strict access control?

**Critical Issues (Deployment Blockers)**:

- SECRET+ data without appropriate controls?
- No encryption at rest or in transit?
- Personnel lacking security clearances?
- No threat model or risk assessment?
- Critical vulnerabilities unpatched?

**Missing MOD SbD Assessment**:

- Project for MOD but no SbD assessment (MANDATORY to run `$arckit-mod-secure`)

#### K. Consistency Across Artifacts

**Terminology Drift**:

- Same concept named differently across files
- Inconsistent capitalization/formatting of terms
- Conflicting definitions

**Data Model Consistency**:

- Data entities referenced in requirements match design
- Database schemas in DLD match data requirements (DR-xxx)
- Data sharing agreements align across artifacts

**Technology Stack Consistency**:

- Stack choices in HLD match principles
- Technology in DLD matches HLD
- Third-party dependencies consistently listed

**Timeline/Budget Consistency** (if vendor procurement):

- SOW timeline realistic for requirements scope?
- Budget adequate for requirements complexity?
- Vendor proposal timeline/budget match SOW?

#### G. Security & Compliance Analysis

**Security Coverage**:

- Security requirements (NFR-S-xxx) exist?
- Threat model documented?
- Security architecture in HLD?
- Security implementation in DLD?
- Security testing plan?

**Compliance Coverage**:

- Compliance requirements (NFR-C-xxx) exist?
- Regulatory requirements identified (GDPR, PCI-DSS, HIPAA, etc.)?
- Compliance validated in design?
- Audit requirements addressed?

**Data Protection**:

- Personal data handling defined?
- GDPR/UK GDPR compliance addressed?
- Data retention policy defined?
- Data breach procedures defined?

### 5. Severity Assignment

Use this heuristic to prioritise findings:

**CRITICAL**:

- Violates architecture principles (MUST)
- Missing core artifact (no ARC-*-REQ-*.md)
- MUST requirement with zero design coverage
- Stakeholder: Orphan requirements (not linked to any stakeholder goal)
- Risk: High/Very High risks with no mitigation in requirements or design
- Risk: Risk owners not from stakeholder RACI matrix (governance gap)
- SOBC: Benefits not traced to stakeholder goals or requirements
- SOBC: Costs inadequate for requirements scope (budget shortfall)
- Data Model: DR-xxx requirements with no entity mapping
- Data Model: PII not identified (GDPR compliance failure)
- Data Model: Data owners not from stakeholder RACI matrix
- UK Gov: TCoP non-compliance for mandatory points
- UK Gov: AI Playbook blocking issues for high-risk AI
- UK Gov: Missing mandatory ATRS for central government AI
- MOD: CAAT not registered (MANDATORY for all programmes)
- MOD: No DTSL appointed (required from Discovery phase)
- MOD: SECRET+ data without classification-specific controls
- MOD: Supplier attestation missing for vendor-delivered system
- Security requirement with no design coverage
- Compliance requirement with no validation

**HIGH**:

- Duplicate or conflicting requirements
- Ambiguous security/performance attribute
- Untestable acceptance criterion
- Missing non-functional requirements category (no security, no performance)
- Stakeholder: Requirement conflicts not documented or resolved
- Risk: Medium risks with no mitigation plan
- Risk: Risk responses not appropriate (4Ts misapplied)
- SOBC: Benefits not measurable or verifiable
- SOBC: Option analysis missing Do Nothing baseline
- Data Model: Database schema in DLD doesn't match data model entities
- Data Model: CRUD matrix doesn't align with HLD component design
- Vendor design doesn't address SOW requirements
- UK Gov: TCoP partial compliance with gaps
- UK Gov: AI Playbook non-compliance for medium-risk AI
- MOD: SbD Principles partially compliant with significant gaps
- MOD: NIST CSF functions not fully covered

**MEDIUM**:

- Terminology drift
- Missing optional non-functional requirement coverage
- Underspecified edge case
- Minor traceability gaps
- Documentation incomplete
- Stakeholder: Missing stakeholder analysis (recommended to add)
- Risk: Missing risk register (recommended to add)
- SOBC: Missing business case (recommended for major investments)
- Data Model: Missing data model (recommended if DR-xxx exist)
- Data Model: Data quality metrics not defined
- UK Gov: TCoP minor gaps
- MOD: CAAT self-assessment incomplete (some question sets missing)
- MOD: Third Line of Defence not fully implemented

**LOW**:

- Style/wording improvements
- Minor redundancy not affecting execution
- Documentation formatting
- Non-critical missing optional fields

### 6. Produce Comprehensive Analysis Report

Generate a comprehensive Markdown report and save it to `projects/{project-dir}/ARC-{PROJECT_ID}-ANAL-v1.0.md` with the following structure:

```markdown
# Architecture Governance Analysis Report

**Project**: {project-name}
**Date**: {current-date}
**Analyzed By**: ArcKit v{version}

---

## Executive Summary

**Overall Status**: ✅ Ready / ⚠️ Issues Found / ❌ Critical Issues

**Key Metrics**:
- Total Requirements: {count}
- Requirements Coverage: {percentage}%
- Critical Issues: {count}
- High Priority Issues: {count}
- Medium Priority Issues: {count}
- Low Priority Issues: {count}

**Recommendation**: [PROCEED / RESOLVE CRITICAL ISSUES FIRST / MAJOR REWORK NEEDED]

---

## Findings Summary

| ID | Category | Severity | Location(s) | Summary | Recommendation |
|----|----------|----------|-------------|---------|----------------|
| R1 | Requirements Quality | HIGH | ARC-*-REQ-*.md:L45-52 | Duplicate security requirements | Merge NFR-S-001 and NFR-S-005 |
| P1 | Principles Alignment | CRITICAL | ARC-*-REQ-*.md:L120 | Violates Cloud-First principle | Change to cloud-native architecture |
| T1 | Traceability | HIGH | No HLD coverage | NFR-P-002 (10K TPS) not addressed | Add performance architecture section to HLD |
| UK1 | UK Gov Compliance | CRITICAL | Missing DPIA | AI system requires DPIA before deployment | Complete DPIA for AI Playbook compliance |

---

## Requirements Analysis

### Requirements Coverage Matrix

| Requirement ID | Type | Priority | Design Coverage | Tests Coverage | Status |
|----------------|------|----------|-----------------|----------------|--------|
| BR-001 | Business | MUST | ✅ HLD | ❌ Missing | ⚠️ Partial |
| FR-001 | Functional | MUST | ✅ HLD, DLD | ✅ Tests | ✅ Complete |
| NFR-S-001 | Security | MUST | ❌ Missing | ❌ Missing | ❌ Not Covered |

**Statistics**:
- Total Requirements: {count}
- Fully Covered: {count} ({percentage}%)
- Partially Covered: {count} ({percentage}%)
- Not Covered: {count} ({percentage}%)

### Uncovered Requirements (CRITICAL)

| Requirement ID | Priority | Description | Why Critical |
|----------------|----------|-------------|--------------|
| NFR-S-003 | MUST | Encrypt data at rest | Security requirement |
| NFR-P-002 | MUST | Support 10K TPS | Performance critical |

---

## Architecture Principles Compliance

| Principle | Status | Evidence | Issues |
|-----------|--------|----------|--------|
| Cloud-First | ✅ COMPLIANT | AWS architecture in HLD | None |
| API-First | ⚠️ PARTIAL | REST APIs defined, missing OpenAPI specs | Document API contracts |
| Security-by-Design | ❌ NON-COMPLIANT | No threat model, missing security architecture | Add security sections |

**Critical Principle Violations**: {count}

---

## Stakeholder Traceability Analysis

**Stakeholder Analysis Exists**: ✅ Yes / ❌ No (RECOMMENDED)

**Stakeholder-Requirements Coverage**:
- Requirements traced to stakeholder goals: {percentage}%
- Orphan requirements (no stakeholder justification): {count}
- Requirement conflicts documented and resolved: ✅ Yes / ⚠️ Partial / ❌ No

**RACI Governance Alignment**:
| Artifact | Role | Aligned with RACI? | Issues |
|----------|------|-------------------|--------|
| Risk Register | Risk Owners | ✅ Yes / ❌ No | Missing 3 risk owners from RACI |
| Data Model | Data Owners | ✅ Yes / ❌ No | None |
| SOBC | Benefits Owners | ✅ Yes / ❌ No | 2 benefits lack owner assignment |

**Critical Issues**:
- Orphan requirements: {count} requirements not linked to stakeholder goals
- Unresolved conflicts: {count} requirement conflicts without resolution

---

## Risk Management Analysis

**Risk Register Exists**: ✅ Yes / ❌ No (RECOMMENDED)

**Risk Coverage**:
| Risk ID | Category | Inherent | Residual | Response | Mitigation in Req? | Mitigation in Design? |
|---------|----------|----------|----------|----------|-------------------|---------------------|
| R-001 | Strategic | Very High | High | Treat | ✅ BR-003 | ✅ HLD Section 4 |
| R-005 | Technology | High | Medium | Treat | ❌ Missing | ❌ Missing |

**High/Very High Risks Requiring Attention**:
| Risk ID | Description | Current Status | Required Action |
|---------|-------------|----------------|-----------------|
| R-005 | Cloud provider lock-in | No mitigation | Add multi-cloud requirements |
| R-012 | Data breach | Partial mitigation | Complete security architecture in HLD |

**Risk-SOBC Alignment** (if SOBC exists):
- Strategic risks reflected in Strategic Case: ✅ Yes / ❌ No
- Financial risks in Economic Case cost contingency: ✅ Yes / ❌ No
- Risks included in Management Case Part E: ✅ Yes / ❌ No

**Risk Governance**:
- Risk owners from stakeholder RACI: ✅ Yes / ⚠️ Partial / ❌ No
- Risk appetite compliance: {count} risks within tolerance

---

## Business Case Analysis

**SOBC Exists**: ✅ Yes / ❌ No (RECOMMENDED for major investments)

**Benefits Traceability**:
| Benefit ID | Description | Stakeholder Goal | Requirements | Measurable? | Status |
|------------|-------------|------------------|--------------|-------------|--------|
| B-001 | Reduce costs 40% | CFO Goal G-1 | BR-002, NFR-P-003 | ✅ Yes | ✅ Complete |
| B-003 | Improve UX | CTO Goal G-5 | FR-008, NFR-A-001 | ❌ No | ❌ Not measurable |

**Benefits Coverage**:
- Total benefits: {count}
- Benefits traced to stakeholder goals: {percentage}%
- Benefits supported by requirements: {percentage}%
- Benefits measurable and verifiable: {percentage}%

**Option Analysis Quality**:
- Do Nothing baseline included: ✅ Yes / ❌ No
- Options analyzed: {count} options
- Recommended option: {option name}
- Justification: ✅ Strong / ⚠️ Weak / ❌ Missing

**SOBC-Requirements Alignment**:
- Strategic Case drivers in requirements: ✅ Yes / ⚠️ Partial / ❌ No
- Economic Case benefits achievable with requirements: ✅ Yes / ⚠️ Questionable / ❌ No
- Financial Case budget adequate: ✅ Yes / ⚠️ Tight / ❌ Insufficient

**Critical Issues**:
- Non-measurable benefits: {count}
- Benefits without requirement support: {count}
- Budget shortfall: £{amount} (requirements scope exceeds budget)

---

## Data Model Analysis

**Data Model Exists**: ✅ Yes / ❌ No (RECOMMENDED if DR-xxx exist)

**DR-xxx Requirements Coverage**:
| Requirement ID | Description | Entities | Attributes | Status |
|----------------|-------------|----------|------------|--------|
| DR-001 | Store customer data | E-001: Customer | customer_id, email, name | ✅ Complete |
| DR-005 | GDPR erasure | E-001: Customer | [All PII] | ✅ Complete |
| DR-008 | Payment history | ❌ No entity | N/A | ❌ Missing |

**Data Requirements Coverage**:
- Total DR-xxx requirements: {count}
- DR-xxx mapped to entities: {percentage}%
- Entities traced to DR-xxx: {percentage}%

**Data Model Quality**:
- ERD exists and renderable: ✅ Yes / ❌ No
- Entities with complete specs: {count}/{total}
- PII identified: ✅ Yes / ⚠️ Partial / ❌ No
- GDPR compliance documented: ✅ Yes / ⚠️ Partial / ❌ No

**Data Governance**:
| Entity | Data Owner (from RACI) | Data Steward | Technical Custodian | Status |
|--------|------------------------|--------------|---------------------|--------|
| E-001: Customer | CFO (from stakeholder RACI) | Data Governance Lead | Database Team | ✅ Complete |
| E-003: Payment | ❌ Not assigned | ❌ Not assigned | Database Team | ❌ Missing owners |

**Data Model-Design Alignment**:
- Database schemas in DLD match entities: ✅ Yes / ⚠️ Partial / ❌ No / N/A
- CRUD matrix aligns with HLD components: ✅ Yes / ⚠️ Partial / ❌ No / N/A
- Data integration flows match upstream/downstream: ✅ Yes / ⚠️ Partial / ❌ No / N/A

**Critical Issues**:
- DR-xxx requirements with no entity mapping: {count}
- PII not identified (GDPR risk): {count} entities
- Data owners not from RACI matrix: {count} entities

---

## UK Government Compliance Analysis

### Technology Code of Practice (TCoP)

**Overall Score**: {score}/130 ({percentage}%)
**Status**: ✅ Compliant / ⚠️ Partial / ❌ Non-Compliant

| Point | Requirement | Status | Score | Issues |
|-------|-------------|--------|-------|--------|
| 1 | Define User Needs | ✅ | 9/10 | Minor: User research from 2023 (update) |
| 5 | Use Cloud First | ✅ | 10/10 | AWS cloud-native |
| 6 | Make Things Secure | ❌ | 3/10 | Missing: Cyber Essentials, threat model |

**Critical TCoP Issues**: {count}

### AI Playbook (if AI system)

**Risk Level**: HIGH-RISK / MEDIUM-RISK / LOW-RISK
**Overall Score**: {score}/160 ({percentage}%)
**Status**: ✅ Compliant / ⚠️ Partial / ❌ Non-Compliant

**Blocking Issues**:
- [ ] DPIA not completed (MANDATORY for high-risk)
- [ ] No human-in-the-loop (REQUIRED for high-risk)
- [ ] ATRS not published (MANDATORY for central government)

### ATRS (if AI system)

**Completeness**: {percentage}%
**Status**: ✅ Ready for Publication / ⚠️ Incomplete / ❌ Missing

**Missing Mandatory Fields**:
- [ ] Senior Responsible Owner
- [ ] Bias testing results
- [ ] Fallback procedures

---

## MOD Secure by Design Analysis

**MOD SbD Assessment Exists**: ✅ Yes / ❌ No (MANDATORY for MOD projects)

**Overall SbD Maturity**: Level {0-5} (Target: Level 3+ for operational systems)

### 7 SbD Principles Compliance

| Principle | Status | Score | Issues |
|-----------|--------|-------|--------|
| 1. Understand and Define Context | ✅ | 9/10 | Minor: Data classification pending final review |
| 2. Apply Security from the Start | ⚠️ | 6/10 | Security architecture not in initial specs |
| 3. Apply Defence in Depth | ❌ | 3/10 | Missing: Network segmentation, IDS/IPS |
| 4. Follow Secure Design Patterns | ✅ | 8/10 | NCSC guidance applied, minor OWASP gaps |
| 5. Continuously Manage Risk | ✅ | 9/10 | Risk register active, continuous monitoring planned |
| 6. Secure the Supply Chain | ⚠️ | 5/10 | Missing: SBOM, supplier attestations |
| 7. Enable Through-Life Assurance | ⚠️ | 6/10 | Monitoring planned, incident response incomplete |

**Overall Score**: {score}/70 ({percentage}%)

### NIST Cybersecurity Framework Coverage

| Function | Status | Coverage | Critical Gaps |
|----------|--------|----------|---------------|
| Identify | ✅ | 90% | Asset inventory incomplete for contractor systems |
| Protect | ⚠️ | 65% | MFA not implemented, PAM missing |
| Detect | ❌ | 40% | No SIEM integration, limited monitoring |
| Respond | ⚠️ | 70% | Incident response plan exists, not tested |
| Recover | ✅ | 85% | Backup/DR tested, BC plan approved |

**Overall CSF Score**: {percentage}%

### Continuous Assurance Process

**CAAT (Cyber Activity and Assurance Tracker)**:
- CAAT registered: ✅ Yes / ❌ No (MANDATORY)
- Registration date: {date}
- Self-assessment question sets completed: {count}/{total}
- Based on 7 SbD Principles: ✅ Yes / ⚠️ Partial / ❌ No
- Continuously updated: ✅ Yes / ⚠️ Sporadic / ❌ One-time only
- Last update: {date}

**Key Roles**:
- Delivery Team Security Lead (DTSL) appointed: ✅ Yes / ❌ No (REQUIRED)
- DTSL name: {name}
- Security Assurance Coordinator (SAC) appointed: ✅ Yes / ❌ No / N/A
- Project Security Officer (PSyO) for SECRET+: ✅ Yes / ❌ No / N/A

### Three Lines of Defence

| Line | Responsibility | Implementation | Status |
|------|----------------|----------------|--------|
| First Line | Delivery team owns security (DTSL) | DTSL appointed, day-to-day management | ✅ Effective |
| Second Line | Technical Coherence assurance | Quarterly reviews scheduled | ⚠️ Partial |
| Third Line | Independent audit (NAO, GIAA) | Pen test planned Q2 | ⚠️ Planned |

**Overall Governance**: ✅ Strong / ⚠️ Adequate / ❌ Weak

### Supplier Attestation (if vendor-delivered)

**Supplier Attestation Required**: ✅ Yes / ❌ No / N/A

**Attestation Status**:
- Suppliers attest systems are secure (ISN 2023/10): ✅ Yes / ❌ No
- Supplier-owned continuous assurance: ✅ Yes / ❌ No
- Supplier security requirements in contracts: ✅ Yes / ⚠️ Partial / ❌ No
- Contract includes CAAT self-assessment obligations: ✅ Yes / ❌ No

### Classification-Specific Requirements

**Data Classification**: OFFICIAL / OFFICIAL-SENSITIVE / SECRET / TOP SECRET

**Classification Requirements Met**:
| Requirement | Status | Evidence |
|-------------|--------|----------|
| Personnel security clearances | ✅ / ❌ | All SC cleared for OFFICIAL-SENSITIVE |
| Cryptography (CESG-approved) | ✅ / ❌ | AES-256, TLS 1.3 |
| Network security (air-gap/assured) | ✅ / ⚠️ / ❌ | Assured connectivity approved |
| Physical security | ✅ / ❌ | Enhanced access controls in place |
| Cyber Essentials / Cyber Essentials Plus | ✅ / ❌ | Cyber Essentials Plus certified |

### Critical Issues (Deployment Blockers)

**Blocking Issues**:
- [ ] CAAT not registered (MANDATORY for all programmes)
- [ ] No DTSL appointed (required from Discovery phase)
- [ ] SECRET+ data without SC cleared personnel
- [ ] No encryption at rest or in transit
- [ ] No threat model or risk assessment
- [ ] Critical vulnerabilities unpatched
- [ ] Supplier attestation missing for vendor-delivered system

**Deployment Readiness**: ✅ Ready / ⚠️ Issues to resolve / ❌ BLOCKED

---

## Traceability Analysis

**Traceability Matrix**: ✅ Exists / ❌ Missing

**Forward Traceability** (Requirements → Design → Tests):
- Requirements → HLD: {percentage}%
- HLD → DLD: {percentage}%
- DLD → Tests: {percentage}%

**Backward Traceability** (Tests → Requirements):
- Orphan components (not linked to requirements): {count}

**Gap Summary**:
- {count} requirements with no design coverage
- {count} design elements with no requirement justification
- {count} components with no test coverage

---

## Vendor Procurement Analysis

### SOW Quality
**Status**: ✅ Complete / ⚠️ Issues / ❌ Insufficient

**Issues**:
- [ ] SOW missing NFR-P-xxx performance requirements
- [ ] Acceptance criteria ambiguous for deliverable 3
- [ ] Timeline unrealistic for scope (6 months vs 50 requirements)

### Vendor Evaluation
**Evaluation Criteria Defined**: ✅ Yes / ❌ No

**Alignment Check**:
- All MUST requirements in scoring? ✅ Yes / ❌ No
- Scoring methodology fair? ✅ Yes / ⚠️ Issues / ❌ No
- Technical evaluation covers all areas? ✅ Yes / ⚠️ Gaps / ❌ No

### Vendor Design Review
**HLD Review Completed**: ✅ Yes / ❌ No
**DLD Review Completed**: ✅ Yes / ❌ No

**Coverage Analysis**:
| SOW Requirement | HLD Coverage | DLD Coverage | Status |
|-----------------|--------------|--------------|--------|
| Cloud infrastructure | ✅ | ✅ | Complete |
| Security architecture | ❌ | ❌ | Missing |
| Performance (10K TPS) | ⚠️ | ❌ | Insufficient |

---

## Security & Compliance Summary

### Security Posture
- Security requirements defined: ✅ Yes / ❌ No
- Threat model documented: ✅ Yes / ❌ No
- Security architecture in HLD: ✅ Yes / ⚠️ Partial / ❌ No
- Security implementation in DLD: ✅ Yes / ⚠️ Partial / ❌ No
- Security testing plan: ✅ Yes / ❌ No

**Security Coverage**: {percentage}%

### Compliance Posture
- Regulatory requirements identified: ✅ Yes / ❌ No
- GDPR/UK GDPR compliance: ✅ Yes / ⚠️ Partial / ❌ No
- Industry compliance (PCI-DSS, HIPAA, etc.): ✅ Yes / ⚠️ Partial / ❌ No / N/A
- Audit readiness: ✅ Yes / ⚠️ Partial / ❌ No

**Compliance Coverage**: {percentage}%

---

## Recommendations

### Critical Actions (MUST resolve before implementation/procurement)

1. **[P1] Add Cloud-First architecture**: Current design violates Cloud-First principle. Redesign with AWS/Azure/GCP.
2. **[R1] Cover security requirements**: NFR-S-003, NFR-S-007, NFR-S-012 have no design coverage. Add security architecture to HLD.
3. **[UK1] Complete DPIA**: HIGH-RISK AI system requires completed DPIA before deployment (AI Playbook MANDATORY).

### High Priority Actions (SHOULD resolve before implementation/procurement)

1. **[T1] Document API contracts**: Add OpenAPI specifications for all REST APIs.
2. **[T2] Add performance architecture**: NFR-P-002 (10K TPS) not addressed in design. Add performance section to HLD.
3. **[V1] Update SOW acceptance criteria**: Deliverable 3 acceptance criteria too vague. Add measurable criteria.

### Medium Priority Actions (Improve quality)

1. **[Q1] Consolidate duplicate requirements**: Merge NFR-S-001 and NFR-S-005 (identical).
2. **[Q2] Fix terminology drift**: "User" vs "Customer" used inconsistently. Standardize.
3. **[D1] Complete traceability matrix**: Add backward traceability from tests to requirements.

### Low Priority Actions (Optional improvements)

1. **[S1] Improve requirement wording**: Replace "fast" with measurable criteria (e.g., "< 200ms p95").
2. **[S2] Add edge case documentation**: Document edge cases for error handling.

---

## Metrics Dashboard

### Requirement Quality
- Total Requirements: {count}
- Ambiguous Requirements: {count}
- Duplicate Requirements: {count}
- Untestable Requirements: {count}
- **Quality Score**: {percentage}%

### Architecture Alignment
- Principles Compliant: {count}/{total}
- Principles Violations: {count}
- **Alignment Score**: {percentage}%

### Traceability
- Requirements Covered: {count}/{total}
- Orphan Components: {count}
- **Traceability Score**: {percentage}%

### Stakeholder Traceability (if applicable)
- Requirements traced to stakeholder goals: {percentage}%
- Orphan requirements: {count}
- Conflicts resolved: {percentage}%
- RACI governance alignment: {percentage}%
- **Stakeholder Score**: {percentage}%

### Risk Management (if applicable)
- High/Very High risks mitigated: {percentage}%
- Risk owners from RACI: {percentage}%
- Risks reflected in design: {percentage}%
- Risk-SOBC alignment: {percentage}%
- **Risk Management Score**: {percentage}%

### Business Case (if applicable)
- Benefits traced to stakeholder goals: {percentage}%
- Benefits supported by requirements: {percentage}%
- Benefits measurable: {percentage}%
- Budget adequacy: ✅ Adequate / ⚠️ Tight / ❌ Insufficient
- **Business Case Score**: {percentage}%

### Data Model (if applicable)
- DR-xxx requirements mapped to entities: {percentage}%
- Entities traced to DR-xxx: {percentage}%
- PII identified: {percentage}%
- Data governance complete: {percentage}%
- Data model-design alignment: {percentage}%
- **Data Model Score**: {percentage}%

### UK Government Compliance (if applicable)
- TCoP Score: {score}/130 ({percentage}%)
- AI Playbook Score: {score}/160 ({percentage}%)
- ATRS Completeness: {percentage}%
- **UK Gov Compliance Score**: {percentage}%

### MOD Compliance (if applicable)
- 7 SbD Principles Score: {score}/70 ({percentage}%)
- NIST CSF Coverage: {percentage}%
- CAAT registered and updated: ✅ Yes / ❌ No
- Three Lines of Defence: {percentage}%
- **MOD SbD Score**: {percentage}%

### Overall Governance Health
**Score**: {percentage}%
**Grade**: A / B / C / D / F

**Grade Thresholds**:
- A (90-100%): Excellent governance, ready to proceed
- B (80-89%): Good governance, minor issues
- C (70-79%): Adequate governance, address high-priority issues
- D (60-69%): Poor governance, major rework needed
- F (<60%): Insufficient governance, do not proceed

---

## Next Steps

### Immediate Actions

1. **If CRITICAL issues exist**: ❌ **DO NOT PROCEED** with implementation/procurement until resolved.
   - Run: `$arckit-requirements` to fix requirements issues
   - Run: `$arckit-hld-review` to address design gaps
   - Run: `$arckit-ai-playbook` (if AI system) to complete mandatory assessments

2. **If only HIGH/MEDIUM issues**: ⚠️ **MAY PROCEED** with caution, but address issues in parallel.
   - Document exceptions for HIGH issues
   - Create remediation plan for MEDIUM issues

3. **If only LOW issues**: ✅ **READY TO PROCEED**
   - Address LOW issues during implementation as improvements

### Suggested Commands

Based on findings, consider running:

**Governance Foundation**:
- `$arckit-principles` - Create/update architecture principles
- `$arckit-stakeholders` - Analyze stakeholder drivers, goals, conflicts (RECOMMENDED)
- `$arckit-risk` - Create risk register using Orange Book framework (RECOMMENDED)
- `$arckit-sobc` - Create Strategic Outline Business Case using Green Book 5-case model (RECOMMENDED for major investments)

**Requirements & Design**:
- `$arckit-requirements` - Refine requirements to address ambiguity/gaps
- `$arckit-data-model` - Create data model with ERD, GDPR compliance (RECOMMENDED if DR-xxx exist)
- `$arckit-hld-review` - Re-review HLD after addressing issues
- `$arckit-dld-review` - Re-review DLD after addressing issues

**UK Government Compliance**:
- `$arckit-tcop` - Complete TCoP assessment for UK Gov projects
- `$arckit-ai-playbook` - Complete AI Playbook assessment for AI systems
- `$arckit-atrs` - Generate ATRS record for algorithmic tools
- `$arckit-secure` - UK Government Secure by Design review

**MOD Compliance**:
- `$arckit-mod-secure` - MOD Secure by Design assessment with CAAT (MANDATORY for MOD projects)

**Vendor Procurement**:
- `$arckit-sow` - Generate statement of work for RFP
- `$arckit-evaluate` - Update vendor evaluation criteria

**Analysis & Traceability**:
- `$arckit-traceability` - Generate/update traceability matrix
- `$arckit-analyze` - Re-run this analysis after fixes

### Re-run Analysis

After making changes, re-run analysis:
```bash
$arckit-analyze
```text

Expected improvement in scores after addressing findings.

---

## Detailed Findings

(Expand top findings with examples and specific recommendations)

### Finding R1: Duplicate Security Requirements (HIGH)

**Location**: `ARC-*-REQ-*.md:L45-52` and `ARC-*-REQ-*.md:L120-125`

**Details**:

```text
NFR-S-001: System MUST encrypt data at rest using AES-256
NFR-S-005: All stored data SHALL be encrypted with AES-256 encryption
```

**Issue**: These are duplicate requirements with inconsistent language (MUST vs SHALL).

**Impact**: Confuses implementation team, wastes evaluation points in vendor scoring.

**Recommendation**:

1. Keep NFR-S-001 (clearer wording)
2. Delete NFR-S-005
3. Update traceability matrix

**Estimated Effort**: 10 minutes

---

### Finding P1: Violates Cloud-First Principle (CRITICAL)

**Location**: `ARC-*-REQ-*.md:L120`, Architecture Principles violation

**Details**:

```text
FR-025: System SHALL deploy to on-premise servers in corporate datacenter
```

**Issue**: Violates "Cloud-First" architecture principle defined in `projects/000-global/ARC-000-PRIN-*.md`. Principle states "MUST use public cloud (AWS/Azure/GCP) unless explicitly justified exception."

**Impact**: Architecture doesn't align with organization standards. Blocks procurement approval.

**Recommendation**:

1. Change FR-025 to require AWS/Azure/GCP deployment
2. OR: Document formal exception with justification (security, regulatory, etc.)
3. Get exception approved by Architecture Review Board

**Estimated Effort**: 2 hours (requirement change + design update)

---

(Continue with detailed findings for top 10-20 issues)

---

## Appendix: Analysis Methodology

**Artifacts Analyzed**:

- {list of files}

**Detection Rules Applied**:

- {count} duplication checks
- {count} ambiguity patterns
- {count} principle validations
- {count} traceability checks

**Analysis Runtime**: {duration}

**Analysis Version**: ArcKit v{version}

---

**END OF ANALYSIS REPORT**

<!-- markdownlint-disable-next-line MD040 -->
```

---

**CRITICAL - Auto-Populate Document Control Fields**:

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

**Construct Document ID**:

- **Document ID**: `ARC-{PROJECT_ID}-ANAL-v{VERSION}` (e.g., `ARC-001-ANAL-v1.0`)

**Populate Required Fields**:

*Auto-populated fields* (populate these automatically):

- `[PROJECT_ID]` → Extract from project path (e.g., "001" from "projects/001-project-name")
- `[VERSION]` → "1.0" (or increment if previous version exists)
- `[DATE]` / `[YYYY-MM-DD]` → Current date in YYYY-MM-DD format
- `[DOCUMENT_TYPE_NAME]` → "Governance Analysis Report"
- `ARC-[PROJECT_ID]-ANAL-v[VERSION]` → Construct using format above
- `[COMMAND]` → "arckit.analyze"

*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 "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

*Calculated fields*:

- `[YYYY-MM-DD]` for Review Date → Current date + 30 days

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

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

**Populate Revision History**:

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

**Populate Generation Metadata Footer**:

The footer should be populated with:

```markdown
**Generated by**: ArcKit `$arckit-analyze` 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-4-5-20250929"]
**Generation Context**: [Brief note about source documents used]
```

---

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

### 7. Write Analysis Report to File

Save the complete analysis report generated in Step 6 to:

**`projects/{project-dir}/ARC-{PROJECT_ID}-ANAL-v1.0.md`**

The saved report must include:

- ✅ All sections from Executive Summary to Detailed Findings
- ✅ Complete metrics dashboard
- ✅ Actionable recommendations with priorities
- ✅ Next steps and suggested commands
- ✅ Traceability to source artifacts

**CRITICAL - Show Summary Only**:
After writing the file, show ONLY the concise summary below. Do NOT output the full analysis report content in your response, as analysis reports can be 1000+ lines with detailed findings and metrics tables.

After writing the file, provide a summary message to the user:

```text
✅ Governance Analysis Complete

**Project**: {project-name}
**Report Location**: projects/{project-dir}/ARC-{PROJECT_ID}-ANAL-v1.0.md

**Overall Status**: ✅ Ready / ⚠️ Issues Found / ❌ Critical Issues
**Governance Health Score**: {score}/100 ({grade})

**Issue Summary**:
- Critical Issues: {count}
- High Priority Issues: {count}
- Medium Priority Issues: {count}
- Low Priority Issues: {count}

**Key Metrics**:
- Requirements Coverage: {percentage}%
- Principles Compliance: {percentage}%
- Traceability Score: {percentage}%
- Stakeholder Alignment: {percentage}%
- Risk Management: {percentage}%
- UK Gov Compliance: {percentage}% (if applicable)
- MOD SbD Compliance: {percentage}% (if applicable)

**Top 3 Critical Issues**:
1. {issue} - {location}
2. {issue} - {location}
3. {issue} - {location}

**Recommendation**: {PROCEED / RESOLVE CRITICAL ISSUES FIRST / MAJOR REWORK NEEDED}

**Next Steps**:
- {action}
- {action}
- {action}

📄 Full analysis report saved to: projects/{project-dir}/ARC-{PROJECT_ID}-ANAL-v1.0.md
```

### 8. Provide Remediation Guidance

After outputting the report, ask:

> **Would you like me to suggest concrete remediation steps for the top {N} critical/high priority issues?**
>
> I can provide:
>
> 1. Specific edits to fix requirements
> 2. Design review guidance
> 3. Command sequences to address gaps
> 4. Templates for missing artifacts
>
> (I will NOT make changes automatically - you must approve each action)

## Operating Principles

### Context Efficiency

- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts

### Analysis Guidelines

- **DO NOT modify existing artifacts** (non-destructive analysis)
- **DO write analysis report** to `projects/{project-dir}/ARC-{PROJECT_ID}-ANAL-v1.0.md`
- **NEVER hallucinate missing sections** (if absent, report them accurately)
- **Prioritize principle violations** (these are always CRITICAL)
- **Prioritize UK Gov compliance issues** (mandatory for public sector)
- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
- **Report zero issues gracefully** (emit success report with metrics)
- **Be specific**: Cite line numbers, requirement IDs, exact quotes
- **Be actionable**: Every finding should have a clear recommendation
- **Be fair**: Flag real issues, not nitpicks

### Enterprise Architecture Focus

Unlike Spec Kit's focus on code implementation, ArcKit analyze focuses on:

- **Governance compliance**: Principles, standards, policies
- **Requirements quality**: Completeness, testability, traceability
- **Procurement readiness**: SOW quality, vendor evaluation fairness
- **Design alignment**: Requirements → design traceability
- **UK Government compliance**: TCoP, AI Playbook, ATRS (if applicable)
- **Security & compliance**: Not just mentioned, but architected
- **Decision quality**: Objective, defensible, auditable

## Example Usage

User: `$arckit-analyze`

You should:

1. Identify project (if multiple, ask which)
2. Load artifacts progressively:
   - Architecture principles
   - Stakeholder drivers (if exists - RECOMMENDED)
   - Risk register (if exists - RECOMMENDED)
   - SOBC business case (if exists - RECOMMENDED)
   - Requirements (BR, FR, NFR, INT, DR)
   - Data model (if exists - RECOMMENDED if DR-xxx)
   - Designs (HLD, DLD)
   - UK Gov assessments (TCoP, AI Playbook, ATRS)
   - MOD assessment (SbD with CAAT)
   - Traceability matrix
3. Run detection passes:
   - Requirements quality (duplication, ambiguity, underspecification)
   - Stakeholder traceability (requirements to goals, conflict resolution, RACI alignment)
   - Risk coverage (high/very high risks mitigated, risk-requirements alignment, risk-SOBC alignment)
   - Business case alignment (benefits to stakeholders, benefits to requirements, costs adequacy)
   - Data model consistency (DR-xxx to entities, data governance, design alignment)
   - Principles alignment (violations, coverage)
   - Traceability (coverage gaps, orphans)
   - UK Gov compliance (TCoP, AI Playbook, ATRS)
   - MOD compliance (7 SbD Principles, NIST CSF, CAAT, Three Lines of Defence)
   - Consistency (terminology, data model, tech stack)
   - Security & compliance coverage
4. Assign severity (CRITICAL, HIGH, MEDIUM, LOW)
5. Generate comprehensive report with:
   - Executive summary
   - Findings table
   - Coverage matrices
   - Stakeholder traceability analysis
   - Risk management analysis
   - Business case analysis
   - Data model analysis
   - UK Gov compliance dashboard
   - MOD compliance dashboard
   - Metrics dashboard
   - Next steps and recommendations
6. Ask if user wants remediation guidance

Example output: "Architecture Governance Analysis Report" with 18 findings (3 CRITICAL, 6 HIGH, 7 MEDIUM, 2 LOW), 87% requirements coverage, 92% stakeholder traceability, 85% risk mitigation, TCoP score 98/130 (75%), MOD SbD score 58/70 (83%), recommendation: "Resolve 3 CRITICAL issues (1 stakeholder orphan, 2 high risks unmitgated) before procurement"

## Important Notes

- This is **non-destructive analysis** - existing artifacts are not modified
- Analysis report is saved to `projects/{project-dir}/ARC-{PROJECT_ID}-ANAL-v1.0.md` for audit trail
- Run `$arckit-analyze` after major changes to requirements, designs, or assessments
- Ideal times to run:
  - Before issuing SOW/RFP to vendors
  - After receiving vendor proposals
  - Before design review meetings
  - Before implementation kickoff
  - Before deployment to production
- Analysis identifies issues; you decide how to resolve them
- Re-run after fixing issues to verify improvements
- Target: 90%+ governance health score before proceeding

- **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

## Related Commands

After analysis, you may need:

**Governance Foundation**:

- `$arckit-principles` - Create/update architecture principles
- `$arckit-stakeholders` - Analyze stakeholder drivers and conflicts
- `$arckit-risk` - Create Orange Book risk register
- `$arckit-sobc` - Create Green Book business case

**Requirements & Data**:

- `$arckit-requirements` - Fix requirements issues
- `$arckit-data-model` - Create data model with ERD and GDPR compliance

**Design Reviews**:

- `$arckit-hld-review` - Re-review high-level design
- `$arckit-dld-review` - Re-review detailed design

**UK Government Compliance**:

- `$arckit-tcop` - Complete TCoP assessment
- `$arckit-ai-playbook` - Complete AI Playbook assessment
- `$arckit-atrs` - Generate ATRS record
- `$arckit-secure` - UK Government Secure by Design review

**MOD Compliance**:

- `$arckit-mod-secure` - MOD Secure by Design assessment with CAAT

**Traceability**:

- `$arckit-traceability` - Update traceability matrix