DavidROliverBA/compliance-check

/compliance-check

Evaluate any architecture artifact against the vault's established architecture principles. Produces a structured compliance assessment with per-principle scoring, evidence mapping, and actionable remediation steps.

Usage

/compliance-check <artifact title>
/compliance-check "ADR - SAP Data Product"
/compliance-check "HLD - Remote Vault Access Architecture"
/compliance-check "LLD - Vault Bot Message Processing"

Arguments

• $ARGUMENTS: The title of the architecture artifact to assess (required). Must match an existing ADR - *.md, HLD - *.md, or LLD - *.md file in the vault.

Supported Artifact Types

| Type | Location | Naming Pattern | |------|----------|----------------| | ADR | ADRs/ | ADR - *.md | | HLD | Root | HLD - *.md | | LLD | Root | LLD - *.md |

Instructions

Phase 1: Load the Target Artifact

1. Parse the command -- extract the artifact title from $ARGUMENTS
2. Find the artifact file:
   • For ADRs: search in ADRs/ folder
   • For HLDs and LLDs: search at vault root
   • If the title does not include the type prefix (ADR -, HLD -, LLD -), try all three locations
   • If not found, search using Grep for partial title matches
   • If still not found, report the error and list available artifacts of each type
3. Read the artifact -- load the full content including frontmatter and body
4. Extract metadata:
   • type -- to confirm it is an architecture artifact
   • relatedTo wiki-links from frontmatter
   • tags for domain context (e.g., domain/security, project/beta)
   • project if specified
   • status (draft, proposed, accepted, etc.)
   • Any inline wiki-links in the body text

Phase 2: Discover Architecture Principles

Principles are stored as Concept notes with conceptType: principle in frontmatter. There are two categories:

1. Individual principle notes -- standalone Concept - *.md files with conceptType: principle
2. Principle collection notes -- notes like Concept - Beta Solution Architecture Principles that contain multiple numbered principles in the body

2.1 Find Individual Principle Notes

The graph index does not include conceptType in its indexed fields. Use Grep to find principle notes:

grep -rl "conceptType: principle" *.md Concept\ -\ *.md

Read each discovered principle note and extract:

• title -- the principle name
• statement -- the principle statement (from statement frontmatter field or the first blockquote in the body)
• implications -- what follows from the principle (from implications frontmatter field)
• domain -- which domain it applies to (from domain frontmatter field)
• tags -- for domain matching against the artifact

2.2 Find Principle Collection Notes

Some notes contain multiple principles as sections (e.g., Concept - Beta Solution Architecture Principles with AP01-AP07). Search for these:

grep -rl "conceptType: principle" Concept\ -\ *.md

For collection notes, extract each individual principle:

• Reference number (e.g., AP01)
• Name (e.g., "Adopt, Don't Adapt")
• One-liner (the blockquote after the heading)
• Statement (the paragraph after the one-liner)
• Fitness Function (the measurable criteria)

2.3 Determine Applicable Principles

Not all principles apply to every artifact. Use domain matching:

1. Check artifact tags -- extract domain tags (e.g., domain/security, project/beta, technology/ai)
2. Check artifact content -- scan for domain indicators (security, data, integration, cloud, AI references)
3. Match principle domains -- a principle applies if:
   • Its domain field matches the artifact's domain tags, OR
   • Its tags overlap with the artifact's tags, OR
   • Its statement/implications are relevant to the artifact's subject matter
4. Project-scoped principles -- if the artifact references a project (e.g., Beta), include project-specific principle collections
5. Universal principles -- principles without a narrow domain scope always apply

If in doubt about applicability, include the principle and mark as NOT APPLICABLE in the output rather than silently excluding it.

Phase 3: Evaluate Compliance

For each applicable principle, assess the artifact against it using this rubric:

| Status | Criteria | |--------|----------| | COMPLIANT | The artifact explicitly addresses this principle. Specific evidence exists in the design, decision rationale, or implementation approach. | | PARTIAL | The artifact partially addresses this principle. Some elements are present but gaps remain -- the principle is not fully satisfied. | | NON-COMPLIANT | The artifact does not address this principle despite it being applicable. The design contradicts the principle, or a relevant concern is entirely absent. | | NOT APPLICABLE | The principle does not apply to this artifact's scope, domain, or context. Justify why. |

How to assess:

1. Read the principle statement and implications carefully
2. Search the artifact for evidence of compliance:
   • Design choices that align with the principle
   • Explicit mentions of the principle's concerns
   • Trade-offs or decisions that satisfy the principle's intent
3. Check for contradictions -- does the artifact make choices that conflict with the principle?
4. Check for gaps -- does the principle raise concerns the artifact should address but does not?
5. For collection principles with fitness functions -- note whether the artifact's approach would pass the fitness function criteria

Phase 4: Generate Compliance Assessment

Output the assessment directly to the console. Use the template below.

---

Output Template

## Principles Compliance Assessment

**Target:** [[{artifact title}]]
**Artifact Type:** {ADR / HLD / LLD}
**Artifact Status:** {status from frontmatter}
**Date:** {today}
**Principles Evaluated:** {count of applicable principles}
**Principles Excluded (not applicable):** {count}

---

### Compliance Summary

| Metric | Count |
|--------|-------|
| **Compliant** | {n} / {total applicable} |
| **Partial** | {n} / {total applicable} |
| **Non-compliant** | {n} / {total applicable} |
| **Not applicable** | {n} / {total evaluated} |

---

### Detailed Assessment

| # | Principle | Source | Status | Evidence | Gap |
|---|-----------|--------|--------|----------|-----|
| 1 | {Principle Title} | [[{source note}]] | COMPLIANT | {where in the artifact this is addressed} | -- |
| 2 | {Principle Title} | [[{source note}]] | PARTIAL | {partially addressed here} | {what is missing} |
| 3 | {Principle Title} | [[{source note}]] | NON-COMPLIANT | -- | {what is missing and why it matters} |
| 4 | {Principle Title} | [[{source note}]] | NOT APPLICABLE | -- | {why this principle does not apply} |

---

### Compliance by Domain

| Domain | Compliant | Partial | Non-compliant | N/A |
|--------|-----------|---------|---------------|-----|
| {domain} | {n} | {n} | {n} | {n} |

---

### Recommended Actions

For each PARTIAL or NON-COMPLIANT principle, provide a specific, actionable remediation step:

1. **{Principle Title}** (PARTIAL)
   - **Gap:** {what is missing}
   - **Action:** {specific change to achieve compliance}
   - **Priority:** {high / medium / low -- based on principle criticality}

2. **{Principle Title}** (NON-COMPLIANT)
   - **Gap:** {what is missing and the risk of non-compliance}
   - **Action:** {specific change to achieve compliance}
   - **Priority:** {high / medium / low}

---

### Context

**Principles sources consulted:**
- [[{principle note 1}]] -- {n} principles
- [[{principle note 2}]] -- {n} principles

**Artifact domain tags:** {list of domain/project tags from the artifact}

**Artifact linked notes:** {list of relatedTo references}

---

*Compliance assessment generated by Claude Code /compliance-check skill. Evaluates document completeness against established principles -- does not assess implementation quality.*

---

Scoring Guidance

COMPLIANT Examples

• Principle says "encrypt data at rest and in transit" -- the artifact specifies TLS for transport and AES-256 for storage
• Principle says "define API contracts" -- the artifact references OpenAPI specifications for each interface
• Principle says "single source of truth for data" -- the artifact designates an authoritative system for each data entity

PARTIAL Examples

• Principle says "encrypt data at rest and in transit" -- the artifact mentions TLS but does not address encryption at rest
• Principle says "design for failure" -- the artifact has an availability target but no recovery procedure
• Principle says "observe everything" -- the artifact mentions logging but not alerting or distributed tracing

NON-COMPLIANT Examples

• Principle says "no point-to-point integrations" -- the artifact proposes a direct database link between two systems
• Principle says "Zero Trust" -- the artifact assumes a trusted network perimeter
• Principle says "adopt, don't adapt" -- the artifact proposes building a custom solution where COTS products exist

NOT APPLICABLE Examples

• A data governance principle assessed against an ADR about UI framework selection
• An AI governance principle assessed against an HLD for a file transfer pipeline
• A project-specific principle (e.g., Beta AP01-AP07) assessed against an artifact for a different project

Examples

Example 1: ADR Compliance Check

/compliance-check "ADR - SAP Data Product"

Evaluates the ADR against all applicable principles -- likely including data governance, integration, and security principles.

Example 2: HLD Compliance Check

/compliance-check "HLD - Remote Vault Access Architecture"

Evaluates the HLD against all applicable principles. For a remote access architecture, security principles (Zero Trust, encryption) and operational principles (observability, failure recovery) would be particularly relevant.

Example 3: Project-Scoped Check

/compliance-check "HLD - SecureTransfer Azure Files to S3 Mirroring"

If the HLD is tagged with project/beta, the Beta Solution Architecture Principles (AP01-AP07) would be included alongside any universal principles.

Error Handling

• Artifact not found: List available ADR, HLD, and LLD notes and ask the user to confirm the title
• No principle notes found: Report that no conceptType: principle notes exist in the vault. Suggest creating principles using the /incubator skill or referencing industry frameworks
• Empty artifact: Report that the artifact has minimal content -- compliance cannot be meaningfully assessed. Flag as INFORMATIONAL
• Artifact is draft status: Proceed with the assessment but note in the output that the artifact is still in draft and compliance gaps may be addressed before finalisation
• No applicable principles: If all principles are NOT APPLICABLE, report this finding and suggest that the artifact's domain may not yet have established principles

Related Skills

• /hld-review -- Full six-dimension HLD review (includes principle compliance as one dimension)
• /nfr-review -- Review against NFR requirements (complementary -- NFRs and principles serve different governance purposes)
• /adr -- Create new ADRs for design choices identified as gaps
• /impact-analysis -- Analyse the impact of changes to systems referenced in the artifact

Related Notes

• Concept - Beta Solution Architecture Principles -- Seven Beta SA principles with fitness functions
• Concept - Beta Digital Team Principles -- Beta Digital Team Principles
• .claude/context/architecture.md -- Architecture governance context
• .claude/context/frontmatter-reference.md -- Frontmatter schemas for ADR, HLD, LLD