architecture-compliance-review

What this skill does

# Architecture Compliance Review Skill

## Purpose

This skill acts as a **compliance portfolio health reviewer**. It validates that all 10 compliance contracts are present and fresh (≤6 months old), analyzes each contract's requirement gaps, and generates an interactive HTML playground for exploring the concept gaps across all contracts — helping you understand which areas of ARCHITECTURE.md fall short of the auto-approve threshold (≥8.0/10) and why.

**Auto-Approve Threshold**: ≥8.0/10 per contract.

**Maximum Contract Age**: 6 months. Any contract older than 6 months is considered EXPIRED and must be regenerated before review proceeds.

---

## When to Invoke This Skill

- User asks to "review compliance contracts", "check compliance coverage", or "assess compliance health"
- User wants to know what must be fixed to reach auto-approve across all contracts
- User asks for a "compliance gap analysis", "compliance dashboard", or "compliance review"
- User wants to explore which ARCHITECTURE.md concepts to update for compliance
- User uses `/skill architecture-compliance-review`

**Do NOT invoke for:**
- Generating new compliance contracts → use `architecture-compliance` skill
- **Recreating, regenerating, or rebuilding compliance contracts or the compliance manifest** → use `architecture-compliance` skill
- Creating or editing ARCHITECTURE.md → use `architecture-docs` skill
- Architecture quality peer review → use `architecture-peer-review` skill
- Business requirements documentation → use `architecture-readiness` skill

---

## Files in This Skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file — entry point and workflow |
| `PLAYGROUND_TEMPLATE.md` | Playground template for the interactive compliance gap explorer HTML |

---

## The 10 Required Compliance Contracts

| # | Contract Type | Identifier Prefix |
|---|---------------|-------------------|
| 1 | SRE Architecture | `SRE_ARCHITECTURE` |
| 2 | Business Continuity | `BUSINESS_CONTINUITY` |
| 3 | Cloud Architecture | `CLOUD_ARCHITECTURE` |
| 4 | Data & AI Architecture | `DATA_AI_ARCHITECTURE` |
| 5 | Development Architecture | `DEVELOPMENT_ARCHITECTURE` |
| 6 | Process Transformation & Automation | `PROCESS_TRANSFORMATION` |
| 7 | Security Architecture | `SECURITY_ARCHITECTURE` |
| 8 | Platform & IT Infrastructure | `PLATFORM_INFRASTRUCTURE` |
| 9 | Enterprise Architecture | `ENTERPRISE_ARCHITECTURE` |
| 10 | Integration Architecture | `INTEGRATION_ARCHITECTURE` |

---

## Workflow

### Step 1 — Locate COMPLIANCE_MANIFEST.md

Search for `compliance-docs/COMPLIANCE_MANIFEST.md` at the project root.

If not found, abort with:
> *"No COMPLIANCE_MANIFEST.md found. Run `/skill architecture-compliance` to generate compliance contracts first, then return here for the review."*

---

### Step 2 — Parse Manifest and Determine Coverage

Read `compliance-docs/COMPLIANCE_MANIFEST.md`. Extract:
- Project name
- For each listed contract: contract type, filename, generation date, status, score

**Get today's date** by running: `bun [plugin_dir]/scripts/today.ts` (cross-platform Bun helper; replaces `date +%Y-%m-%d` so the skill runs identically on Linux, macOS, Windows native, WSL, and Git Bash)

**6-month cutoff rule**: A contract is VALID only if its generation date is within 6 calendar months of today. Compute the cutoff date = today minus 6 months (e.g., if today is 2026-03-22, the cutoff is 2025-09-22).

**For each of the 10 required contract types**, determine:
- **present**: Is the contract listed in the manifest? Confirm the file exists in `compliance-docs/` using Glob.
- **fresh**: Is the generation date on or after the 6-month cutoff?
- **contract_status**: `valid` | `missing` | `expired`

Build a coverage summary table and display it to the user:

```
| # | Contract Type                 | Status    | Generation Date | Age      | Score   |
|---|-------------------------------|-----------|-----------------|----------|---------|
| 1 | SRE Architecture              | ✅ Valid  | 2025-12-27      | 2.8 mo   | 7.69/10 |
| 2 | Business Continuity           | ❌ Missing | —              | —        | —       |
| 3 | Security Architecture         | ⚠️ Expired | 2025-01-15     | 14.2 mo  | 6.5/10  |
| … | …                             | …         | …               | …        | …       |
```

---

### Step 3 — Handle Missing and Expired Contracts

If **all 10 contracts are valid**, skip to Step 4.

If any contracts are `missing` or `expired`, present the user with a choice:

> **N contract(s) are missing or expired and cannot be included in this review.**
>
> **[A] Regenerate now** — invoke the `architecture-compliance` skill for the affected contracts, then continue the review
> **[B] Proceed with valid contracts only** — review covers only the valid contracts; missing/expired will be marked as NOT REVIEWED
> **[C] Cancel** — stop here and regenerate contracts manually with `/skill architecture-compliance`

- **Option A**: Invoke the `architecture-compliance` skill specifying only the affected contract types. Wait for completion. Re-read the manifest. Proceed to Step 4.
- **Option B**: Proceed to Step 4 with the available valid contracts. Track missing/expired contracts separately as NOT REVIEWED items in the playground data.
- **Option C**: Abort with guidance to use `/skill architecture-compliance`.

---

### Step 4 — Read Contract Files for Gap Extraction

For each contract with `contract_status = valid`, read the actual file from `compliance-docs/`.

From each contract file, extract the following data:

#### 4a. Score and Requirement Breakdown

Locate the Document Control section (table with `| Field | Value |` format) or the score summary. Extract:
- Current score (e.g., `7.69/10`)
- Projected score after resolving all Unknown gaps (if stated)

Locate the requirement breakdown section. Extract counts for:
- Blocker requirements: total, compliant, not applicable, unknown, non-compliant
- Desired requirements: total, compliant, not applicable, unknown, non-compliant

#### 4b. Gap Rows from Compliance Summary Table

Locate the **Compliance Summary Table** — a 6-column table with headers:
`| Code | Requirement | Category | Status | Source Section | Responsible Role |`

Extract every row where `Status` = `Non-Compliant` OR `Status` = `Unknown`.

For each gap row, capture:
- `code`: requirement code (e.g., `SRE-B-023`)
- `requirement`: full requirement text
- `category`: compliance category
- `status`: `Non-Compliant` or `Unknown`
- `sourceSection`: ARCHITECTURE.md source section reference
- `priority`: determine whether this is a **Blocker** or **Desired** requirement by checking which section heading precedes the row (e.g., "Blocker Requirements" or "Desired Requirements")

**Assign concept tags** to each gap based on requirement text keywords:
- Load testing, stress testing, performance testing → `["load-testing", "performance"]`
- Chaos engineering, fault injection → `["chaos-engineering", "resilience"]`
- RTO, RPO, DR, disaster recovery → `["dr-rto-rpo", "business-continuity"]`
- IAM, RBAC, authentication, authorization → `["iam", "access-control"]`
- Monitoring, observability, alerting, SLO, SLA → `["observability", "monitoring"]`
- Data retention, data classification, data governance → `["data-governance"]`
- CI/CD, pipeline, deployment automation → `["cicd", "deployment"]`
- API documentation, API contracts, OpenAPI → `["api-docs", "integration"]`
- Encryption, TLS, mTLS, certificates → `["encryption", "security"]`
- Incident management, runbooks, SOPs, on-call → `["incident-management", "operations"]`
- Capacity planning, scaling, auto-scaling → `["capacity-planning", "scalability"]`
- Compliance framework, audit, GDPR, SOC2 → `["regulatory-compliance"]`

---

### Step 5 — Compute Gap Analysis

#### 5a. Per-Contract Auto-Approve Gap

For each valid contract, compute:
- `aboveThreshold`: score ≥ 8.0
- `gapToThreshold`: max(0, 8.0 − score)
- Estimated score if all Unknown gaps resolved t