From evaluation-tools
Systematic completeness audit of Architecture Documentation using 188-item viewpoint-based checklist, severity-classified gap detection, technical debt indicators, and architecture anti-pattern scanning. Supports TOGAF, C4, arc42, and IEEE 42010 frameworks. PROACTIVELY activate for: (1) Architecture review gates, (2) ADR validation before implementation, (3) C4 diagram completeness check, (4) Technical debt assessment, (5) Pre-implementation validation, (6) Governance compliance audit, (7) Design doc handoff review. Triggers: "audit architecture", "review ADR", "check architecture doc", "validate design doc", "architecture review", "audit C4 diagrams", "check system context", "technical debt assessment", "architecture health check", "governance review", "architecture completeness"
How this skill is triggered — by the user, by Claude, or both
Slash command
/evaluation-tools:architecture-doc-auditorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A systematic audit system that evaluates Architecture Documentation against a comprehensive 188-item viewpoint-based checklist, detecting gaps, classifying severity, identifying technical debt signals, scanning for architecture anti-patterns, and generating actionable remediation roadmaps. Implements the GAP-AUDIT pattern (PATTERN-08) to produce CONTRACT-07 compliant GAP-INVENTORY output with A...
references/anti-patterns-catalog.mdreferences/architecture-checklist.mdreferences/architecture-standards.mdreferences/checkpoints.yamlreferences/compliance-frameworks.mdreferences/quality-attributes.mdreferences/technical-debt-indicators.mdreferences/viewpoint-catalog.mdtemplates/architecture-health-report.mdtemplates/debt-remediation-roadmap.mdtemplates/gap-inventory-output.mdA systematic audit system that evaluates Architecture Documentation against a comprehensive 188-item viewpoint-based checklist, detecting gaps, classifying severity, identifying technical debt signals, scanning for architecture anti-patterns, and generating actionable remediation roadmaps. Implements the GAP-AUDIT pattern (PATTERN-08) to produce CONTRACT-07 compliant GAP-INVENTORY output with Architecture Health Score extensions.
This skill provides 12 core capabilities:
| # | Capability | Phase | Description |
|---|---|---|---|
| 1 | Framework Detect | 1 | Identify architecture framework (TOGAF, C4, arc42, IEEE 42010) |
| 2 | Document Parse | 1 | Extract architecture structure, diagrams, and decision records |
| 3 | Viewpoint Map | 2 | Apply 14-viewpoint coverage framework to document sections |
| 4 | Item-by-Item Verify | 3 | Check each of 188 checklist items against content |
| 5 | Gap Detect | 3 | Identify missing, incomplete, or inconsistent elements |
| 6 | Classify Gap Type | 4 | Categorize gaps using 6-type taxonomy |
| 7 | Score Severity | 4 | Apply RUBRIC-07 (impact, likelihood, detectability) |
| 8 | Anti-Pattern Scan | 5 | Detect 25 architecture anti-patterns |
| 9 | Debt Signal Detect | 5 | Identify 25+ technical debt indicators |
| 10 | Quality Attribute Validate | 4 | Verify ISO 25010 quality attribute coverage |
| 11 | Remediate Suggest | 5 | Generate fix recommendations with effort estimates |
| 12 | Synthesize Report | 6 | Produce GAP-INVENTORY + Health Score + Debt Roadmap |
Ideal for:
Avoid when:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
document | string | yes | — | Architecture document content or file reference |
document_type | enum | no | design_doc | adr | design_doc | system_context | container | component | deployment | sequence | data_flow |
framework | enum | no | auto | togaf | c4 | arc42 | ieee_42010 | custom | auto |
audit_depth | enum | no | standard | surface | standard | exhaustive |
viewpoints | list | no | core_10 | List of viewpoint IDs (V1-V14) to validate |
quality_attributes | list | no | all | ISO 25010 attributes to validate |
include_debt_assessment | boolean | no | true | Whether to scan for technical debt indicators |
include_anti_patterns | boolean | no | true | Whether to scan for architecture anti-patterns |
governance_context | enum | no | team | enterprise | team | project |
output_format | enum | no | full | full | executive | debt_roadmap_only |
| Type | Primary Viewpoints | Checklist Focus |
|---|---|---|
| adr | V10 | Decision structure, rationale, consequences |
| design_doc | V1-V10 | Full viewpoint coverage |
| system_context | V1, V6, V7 | External actors, integrations, boundaries |
| container | V2, V5, V6 | Technology choices, communication patterns |
| component | V3, V6 | Internal structure, interfaces |
| deployment | V4, V8 | Infrastructure, scaling, operations |
| sequence | V6 | API flows, interaction patterns |
| data_flow | V5, V7 | Data stores, flows, security |
| Depth | Behavior |
|---|---|
| surface | Critical items only (~60 items), structural gaps, no anti-patterns |
| standard | Full checklist for relevant viewpoints, anti-patterns, standard remediation |
| exhaustive | All viewpoints including conditional, deep anti-pattern analysis, debt indicators, detailed remediation |
| Context | Compliance Level | Output Focus |
|---|---|---|
| enterprise | Full compliance frameworks (SOC2, GDPR, PCI-DSS) | Governance reporting, compliance matrix |
| team | Standard architecture practices | Team handoff, implementation readiness |
| project | Minimal viable documentation | Quick assessment, critical gaps only |
Purpose: Load document and establish audit context.
Steps:
architecture-checklist.md referencedocument_type:
viewpoint-catalog.md for structural validationTechniques Used:
document_structure_extraction - Parse document hierarchyframework_detection - Identify architecture methodologychecklist_calibration - Adjust criteria for contextQuality Gate: Framework identified; checklist calibrated for document type; structure parsed with sections identified
Output: Calibrated checklist (N items) + Document structure map + Detected framework
Purpose: Map document sections to architecture viewpoints and identify structural gaps.
Steps:
Load viewpoint framework from viewpoint-catalog.md:
Core Viewpoints (Always Assess):
Conditional Viewpoints (If Applicable):
Map each document section to viewpoints:
Identify structural gaps:
Check for applicable conditional viewpoints:
Calculate initial coverage score per viewpoint
Techniques Used:
completeness_verification (CAT-PR-GA) - Verify all viewpoints addressedviewpoint_mapping - Map sections to architectural concernsQuality Gate: All applicable viewpoints assessed; structural gaps flagged
Output: Viewpoint coverage map with scores and structural gap list
Purpose: Verify each checklist item against document content.
Steps:
For each checklist item (V1-01 through V10-20):
1. LOCATE RELEVANT SECTION
└─ Based on viewpoint mapping from Phase 2
2. ASSESS PRESENCE
├─ PRESENT: Item clearly addressed
├─ PARTIAL: Item mentioned but incomplete
└─ ABSENT: No evidence of item
3. EVALUATE QUALITY (if present)
├─ CLEAR: Unambiguous and actionable
├─ AMBIGUOUS: Multiple interpretations possible
├─ INCONSISTENT: Contradicts other content
├─ INCOMPLETE: Missing key details
└─ OUTDATED: Stale or deprecated references
4. RECORD EVIDENCE
├─ Location: Section/diagram reference
├─ Quote: Supporting text from document
└─ Assessment: Pass/fail with rationale
5. FLAG FOR GAP CLASSIFICATION (if needed)
└─ Any non-PRESENT or non-CLEAR items
Verification Rules by Viewpoint:
| Viewpoint | Items | Critical Items | Verification Approach |
|---|---|---|---|
| V1: Context | V1-01 to V1-15 | V1-01, V1-02, V1-03 | Check boundary definition, external actors |
| V2: Container | V2-01 to V2-25 | V2-01, V2-02, V2-05 | Verify technology choices documented |
| V3: Component | V3-01 to V3-18 | V3-01, V3-02 | Check internal structure clarity |
| V4: Deployment | V4-01 to V4-22 | V4-01, V4-05, V4-10 | Verify infrastructure defined |
| V5: Data | V5-01 to V5-18 | V5-01, V5-02, V5-05 | Check data stores and flows |
| V6: Integration | V6-01 to V6-15 | V6-01, V6-02, V6-05 | Verify API contracts exist |
| V7: Security | V7-01 to V7-25 | V7-01, V7-02, V7-05, V7-10 | Check auth, encryption, audit |
| V8: Operations | V8-01 to V8-18 | V8-01, V8-05, V8-10 | Verify monitoring, SLOs defined |
| V9: Cross-Cutting | V9-01 to V9-12 | V9-01, V9-05 | Check logging, config patterns |
| V10: Decisions | V10-01 to V10-20 | V10-01, V10-02, V10-05 | Verify ADR structure and coverage |
Techniques Used:
completeness_verification (CAT-PR-GA) - Check presence of each itemnegative_space_analysis (CAT-PR-GA) - Identify what's NOT documentedconsistency_check (CAT-PR-ECR) - Cross-reference between viewpointsQuality Gate: 100% of applicable checklist items evaluated
Output: Verification matrix with item-level results and evidence
Purpose: Validate coverage of ISO 25010 quality attributes.
Steps:
Map document content to quality attributes from quality-attributes.md:
| Quality Attribute | Primary Viewpoints | Validation Criteria |
|---|---|---|
| Performance | V4, V5 | Latency targets, throughput requirements, resource limits |
| Scalability | V4, V2 | Scaling strategy, elasticity approach, capacity planning |
| Security | V7, V6 | Auth mechanisms, encryption, audit logging, compliance |
| Reliability | V8, V4 | Availability targets, fault tolerance, DR strategy |
| Maintainability | V3, V10 | Modularity, testability, decision rationale |
| Interoperability | V6, V1 | API standards, protocol choices, versioning |
| Portability | V4, V2 | Platform dependencies, abstraction layers |
| Usability | V6, V10 | API ergonomics, developer experience |
For each quality attribute:
Flag quality attribute gaps:
Techniques Used:
quality_attribute_validation - Map concerns to ISO 25010coverage_assessment - Evaluate attribute coverageQuality Gate: All quality attributes assessed with coverage level
Output: Quality attribute coverage matrix
Purpose: Identify technical debt signals and architecture anti-patterns.
Steps:
For each gap identified in Phases 3-4, apply gap taxonomy (from gap-taxonomy.md):
IS ELEMENT PRESENT?
├─ NO → MISSING
└─ YES
├─ IS IT COMPLETE?
│ ├─ NO → INCOMPLETE
│ └─ YES
│ ├─ DOES IT CONTRADICT OTHER CONTENT?
│ │ ├─ YES → INCONSISTENT
│ │ └─ NO
│ │ ├─ IS IT CLEAR AND UNAMBIGUOUS?
│ │ │ ├─ NO → AMBIGUOUS
│ │ │ └─ YES
│ │ │ ├─ IS IT TECHNICALLY CORRECT?
│ │ │ │ ├─ NO → INCORRECT
│ │ │ │ └─ YES
│ │ │ │ └─ IS IT CURRENT?
│ │ │ │ ├─ NO → OUTDATED
│ │ │ │ └─ YES → No gap
Apply SEVERITY-SCORING (RUBRIC-07) with three dimensions:
| Dimension | Weight | Scale |
|---|---|---|
| Impact | 0.5 | 1=Low, 2=Medium, 3=High, 4=Critical |
| Likelihood | 0.3 | 1=Rare, 2=Possible, 3=Likely, 4=Certain |
| Detectability | 0.2 | 1=Obvious, 2=Moderate, 3=Difficult, 4=Hidden |
Calculation:
severity_score = (impact × 0.5) + (likelihood × 0.3) + (detectability × 0.2)
CRITICAL: score >= 3.5
HIGH: 2.5 <= score < 3.5
MEDIUM: 1.5 <= score < 2.5
LOW: score < 1.5
If include_anti_patterns is true, scan for 25 patterns from anti-patterns-catalog.md:
Structural Anti-Patterns:
| ID | Anti-Pattern | Severity | Detection Signal |
|---|---|---|---|
| AA-01 | Big Ball of Mud | CRITICAL | No clear component boundaries |
| AA-02 | Distributed Monolith | CRITICAL | Microservices with tight coupling |
| AA-03 | Database Monolith | HIGH | All services sharing single database |
| AA-04 | God Service | HIGH | One service handling everything |
| AA-05 | Circular Dependencies | CRITICAL | A depends on B depends on A |
| AA-06 | Golden Hammer | MEDIUM | Same tech used regardless of fit |
| AA-07 | Vendor Lock-in Blindness | HIGH | No abstraction over proprietary services |
| AA-08 | Accidental Complexity | HIGH | Over-engineering indicators |
Documentation Anti-Patterns:
| ID | Anti-Pattern | Severity | Detection Signal |
|---|---|---|---|
| AA-09 | Diagram Divorce | CRITICAL | Diagrams don't match text |
| AA-10 | ADR Amnesia | HIGH | Decisions made without records |
| AA-11 | Stale Blueprints | HIGH | Docs reference deprecated systems |
| AA-12 | View Vacuum | CRITICAL | Missing entire viewpoint |
| AA-13 | C4 Confusion | MEDIUM | Mixed abstraction levels in diagrams |
| AA-14 | Prose Overload | MEDIUM | Walls of text, no diagrams |
| AA-15 | Technology Tourism | LOW | Tech name-dropping without rationale |
| AA-16 | Abstraction Allergy | MEDIUM | Only code-level detail, no conceptual |
Operational Anti-Patterns:
| ID | Anti-Pattern | Severity | Detection Signal |
|---|---|---|---|
| AA-17 | Observability Omission | HIGH | No monitoring/alerting strategy |
| AA-18 | SLO Silence | HIGH | No reliability targets |
| AA-19 | Deployment Darkness | CRITICAL | No deployment documentation |
| AA-20 | Capacity Blindness | HIGH | No scaling strategy |
| AA-21 | Runbook Roulette | MEDIUM | No operational procedures |
Security Anti-Patterns:
| ID | Anti-Pattern | Severity | Detection Signal |
|---|---|---|---|
| AA-22 | Trust Assumption | CRITICAL | "Internal network is secure" |
| AA-23 | Auth Afterthought | HIGH | Security bolted on later |
| AA-24 | Secret Scatter | CRITICAL | Credentials in configs/code |
| AA-25 | Compliance Complacency | HIGH | No compliance mapping |
If include_debt_assessment is true, scan for indicators from technical-debt-indicators.md:
| Category | Indicators | Severity Range |
|---|---|---|
| Architectural Debt | Shared databases, sync coupling, missing abstractions | HIGH-CRITICAL |
| Documentation Debt | Stale diagrams, missing rationale, undocumented interfaces | MEDIUM-HIGH |
| Infrastructure Debt | Manual deployments, missing DR, hardcoded config | MEDIUM-HIGH |
| Security Debt | Undocumented auth, missing encryption, no audit strategy | HIGH-CRITICAL |
| API Debt | Breaking changes, no versioning, inconsistent contracts | MEDIUM-HIGH |
Match each gap to remediation pattern:
| Gap Type | Primary Pattern | Action |
|---|---|---|
| MISSING | Add Content | Write new section using template |
| INCOMPLETE | Expand Content | Fill in missing details |
| INCONSISTENT | Reconcile Content | Resolve contradictions |
| AMBIGUOUS | Clarify Content | Add specificity/metrics |
| INCORRECT | Correct Content | Fix technical errors |
| OUTDATED | Update Content | Refresh stale information |
Effort Estimation:
| Effort Level | Definition | Time Range |
|---|---|---|
| trivial | Quick fix, obvious solution | < 30 min |
| small | Clear scope, single viewpoint | 30 min - 2 hours |
| medium | Multiple viewpoints or research needed | 2 - 8 hours |
| large | Significant rework or stakeholder input | 1+ days |
Techniques Used:
severity_scoring (RUBRIC-07) - Score gaps by impactfull_consistency_matrix (CAT-PR-ECR) - Cross-reference for inconsistenciesanti_pattern_detection - Match known failure patternsdebt_signal_detection - Identify technical debt indicatorsQuality Gate: All gaps classified with type and severity; anti-patterns and debt signals detected
Output: Classified gap list + Anti-pattern findings + Debt indicators
Purpose: Produce final GAP-INVENTORY artifact with Architecture Health Score.
Steps:
Compile all findings into CONTRACT-07 compliant structure:
source_reference with document identifiersource_type to "architecture"audit_criteria with viewpoint-based checklistgaps array with all classified gapsanti_patterns array if detectedtechnical_debt section with indicatorssummary statisticsCalculate overall architecture health:
<architecture_health>
<overall_score>[0-100]</overall_score>
<by_viewpoint>
<!-- Score per viewpoint -->
</by_viewpoint>
<by_quality_attribute>
<!-- Coverage per ISO 25010 attribute -->
</by_quality_attribute>
<technical_debt_summary>
<!-- Debt indicator counts by category -->
</technical_debt_summary>
<c4_maturity>
<!-- Completeness of C4 levels if applicable -->
</c4_maturity>
</architecture_health>
Health Score Calculation:
viewpoint_score = (items_passed / items_total) × 100 per viewpoint
overall_score = weighted_average(viewpoint_scores) - severity_penalties
Severity Penalties:
- CRITICAL gap: -10 points
- HIGH gap: -5 points
- Anti-pattern: -3 points
- Debt indicator: -2 points
Health Status Thresholds:
| Status | Score Range | Interpretation |
|---|---|---|
| HEALTHY | 80-100 | Ready for implementation |
| ADEQUATE | 60-79 | Minor gaps, proceed with awareness |
| AT_RISK | 40-59 | Significant gaps, address before proceeding |
| CRITICAL | 0-39 | Major gaps, not ready for implementation |
Generate:
total_gaps: Count of all gapsby_severity: {critical: N, high: N, medium: N, low: N}by_category: {missing: N, incomplete: N, inconsistent: N, ...}by_viewpoint: Gap count per viewpointoverall_assessment: Based on health scoreblocking_issues: List of gap IDs that must be fixedcoverage_score: Percentage of checklist items passedAssessment Thresholds:
| Assessment | Criteria |
|---|---|
| critical_issues | Any CRITICAL gap OR overall_score < 40 |
| significant_gaps | No CRITICAL but score 40-59 OR >3 HIGH gaps |
| minor_issues | Score 60-79, only MEDIUM/LOW gaps |
| acceptable | Score 80-89, few gaps |
| excellent | Score 90+, minimal gaps |
Generate stakeholder-friendly summary:
Generate prioritized technical debt paydown plan:
Based on output_format parameter:
Techniques Used:
artifact_synthesis - Compile structured outputhealth_score_calculation - Compute architecture healthstakeholder_communication - Tailor for audienceQuality Gate: Output validates against CONTRACT-07 schema with architecture extensions
Output: GAP-INVENTORY artifact + Architecture Health Score + requested summaries
| # | Type | Definition | Architecture Detection Signal | Remediation |
|---|---|---|---|---|
| 1 | MISSING | Required element completely absent | No viewpoint coverage, no ADRs found, deployment undocumented | Add content |
| 2 | INCOMPLETE | Present but lacking required detail | TBD in diagrams, partial API specs, rationale missing | Expand content |
| 3 | INCONSISTENT | Contradicts other sections | Context shows 5 services, container shows 8; ADR contradicts implementation | Reconcile content |
| 4 | AMBIGUOUS | Multiple interpretations possible | "Scalable architecture" without metrics, "secure by design" without controls | Clarify content |
| 5 | INCORRECT | Technically wrong information | References deprecated API, shows removed service, wrong technology | Correct content |
| 6 | OUTDATED | Was correct but no longer current | Shows v1 API when v3 current, references decommissioned database | Update content |
Reference: See references/architecture-checklist.md for detailed detection heuristics per checklist item.
Aligns with CONTRACT-07 from artifact-contracts.yaml with architecture extensions.
<?xml version="1.0" encoding="UTF-8"?>
<gap_inventory contract="CONTRACT-07" version="1.0">
<metadata>
<artifact_id>GI-ARCH-[YYYY-MM-DD]-[5-char-hash]</artifact_id>
<contract_type>GAP-INVENTORY</contract_type>
<created_at>[ISO 8601]</created_at>
<created_by>architecture-doc-auditor</created_by>
<confidence>[0.0-1.0]</confidence>
<provenance>
<source_artifact>[Document identifier]</source_artifact>
<audit_date>[ISO 8601 date]</audit_date>
<audit_depth>[surface|standard|exhaustive]</audit_depth>
<document_type>[adr|design_doc|system_context|...]</document_type>
<framework_detected>[togaf|c4|arc42|ieee_42010|custom]</framework_detected>
<checklist_version>1.0</checklist_version>
<items_checked>[N]</items_checked>
<viewpoints_assessed>[list]</viewpoints_assessed>
</provenance>
</metadata>
<source_reference>[Document identifier]</source_reference>
<source_type>architecture</source_type>
<audit_criteria>
<checklist_reference>architecture-checklist.md v1.0</checklist_reference>
<viewpoint_framework>viewpoint-catalog.md v1.0</viewpoint_framework>
<criteria_list>
<criterion id="[V1-01]" viewpoint="V1">[Item description]</criterion>
<!-- All checked items -->
</criteria_list>
<coverage_scope>[What this audit covered]</coverage_scope>
</audit_criteria>
<gaps>
<gap id="GAP-001">
<category>[missing|incomplete|inconsistent|ambiguous|incorrect|outdated]</category>
<severity>[critical|high|medium|low]</severity>
<severity_score>
<impact>[1-4]</impact>
<likelihood>[1-4]</likelihood>
<detectability>[1-4]</detectability>
<composite>[calculated]</composite>
</severity_score>
<viewpoint>[V1-V14]</viewpoint>
<checklist_ref>[V1-01]</checklist_ref>
<location>[Document section/diagram]</location>
<description>[Gap description]</description>
<evidence>[What indicates this gap]</evidence>
<impact>[Consequence if not addressed]</impact>
<remediation>
<recommendation>[How to fix]</recommendation>
<effort>[trivial|small|medium|large]</effort>
<priority>[immediate|short_term|medium_term|long_term]</priority>
</remediation>
</gap>
</gaps>
<anti_patterns>
<pattern id="AA-02">
<name>Distributed Monolith</name>
<severity>CRITICAL</severity>
<instances>
<instance location="[section]">[Evidence quote]</instance>
</instances>
<remediation>[How to address]</remediation>
</pattern>
</anti_patterns>
<technical_debt>
<indicator id="TD-A01">
<category>architectural</category>
<name>Shared database between services</name>
<severity>HIGH</severity>
<evidence>[Where detected]</evidence>
<remediation_cost>large</remediation_cost>
</indicator>
</technical_debt>
<architecture_health>
<overall_score>[0-100]</overall_score>
<overall_status>[HEALTHY|ADEQUATE|AT_RISK|CRITICAL]</overall_status>
<by_viewpoint>
<viewpoint id="V1" name="Context & Scope" score="[0-100]" status="[status]"/>
<viewpoint id="V2" name="Container" score="[0-100]" status="[status]"/>
<!-- All assessed viewpoints -->
</by_viewpoint>
<by_quality_attribute>
<attribute name="Performance" coverage="[EXPLICIT|IMPLICIT|MISSING]"/>
<attribute name="Security" coverage="[EXPLICIT|IMPLICIT|MISSING]"/>
<!-- All quality attributes -->
</by_quality_attribute>
<technical_debt_summary>
<total_indicators>[N]</total_indicators>
<by_category>
<architectural>[N]</architectural>
<documentation>[N]</documentation>
<infrastructure>[N]</infrastructure>
<security>[N]</security>
<api>[N]</api>
</by_category>
</technical_debt_summary>
<c4_maturity>
<level_1_complete>[true|false]</level_1_complete>
<level_2_complete>[true|false]</level_2_complete>
<level_3_complete>[true|false]</level_3_complete>
<level_4_complete>[true|false]</level_4_complete>
</c4_maturity>
</architecture_health>
<summary>
<total_gaps>[N]</total_gaps>
<by_severity>
<critical>[N]</critical>
<high>[N]</high>
<medium>[N]</medium>
<low>[N]</low>
</by_severity>
<by_category>
<missing>[N]</missing>
<incomplete>[N]</incomplete>
<inconsistent>[N]</inconsistent>
<ambiguous>[N]</ambiguous>
<incorrect>[N]</incorrect>
<outdated>[N]</outdated>
</by_category>
<by_viewpoint>
<v1>[N]</v1>
<v2>[N]</v2>
<!-- Gap count per viewpoint -->
</by_viewpoint>
<anti_patterns_detected>[N]</anti_patterns_detected>
<debt_indicators_detected>[N]</debt_indicators_detected>
<overall_assessment>[critical_issues|significant_gaps|minor_issues|acceptable|excellent]</overall_assessment>
<blocking_issues>
<issue ref="GAP-001">[Brief description]</issue>
</blocking_issues>
<coverage_score>
<items_passed>[N]</items_passed>
<items_total>[N]</items_total>
<percentage>[X%]</percentage>
</coverage_score>
</summary>
</gap_inventory>
See templates/architecture-health-report.md for complete template.
See templates/debt-remediation-roadmap.md for complete template.
| # | Gate | Criterion | Phase |
|---|---|---|---|
| 1 | Framework Detected | Architecture methodology identified or marked as custom | 1 |
| 2 | Checklist Calibrated | Checklist adjusted for document type with applicable items | 1 |
| 3 | Document Parsed | All sections identified with structure map created | 1 |
| 4 | Viewpoints Mapped | All applicable viewpoints assessed with scores | 2 |
| 5 | Items Verified | 100% of applicable checklist items evaluated | 3 |
| 6 | Quality Attributes Checked | All ISO 25010 attributes assessed for coverage | 4 |
| 7 | Gaps Classified | All gaps assigned type from 6-type taxonomy | 5 |
| 8 | Severity Scored | All gaps scored using 3-dimension RUBRIC-07 | 5 |
| 9 | Anti-Patterns Scanned | All 25 anti-patterns checked (if enabled) | 5 |
| 10 | Debt Indicators Scanned | All debt categories checked (if enabled) | 5 |
| 11 | Health Score Calculated | Overall architecture health score computed | 6 |
| 12 | Output Validated | GAP-INVENTORY conforms to CONTRACT-07 schema | 6 |
This skill serves as a quality gate in the architecture development workflow:
┌─────────────────────────────────────┐
│ ARCHITECTURE DOC AUDITOR │ ◀── THIS SKILL
│ │
└────────────────┬────────────────────┘
│
│ Input: Architecture Document
│
▼
┌─────────────────────────────────────┐
│ Phase 1: Intake & Framework │
│ • Detect framework (C4/arc42/...) │
│ • Load architecture-checklist │
│ • Parse document structure │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 2: Viewpoint Mapping │
│ • Apply 14-viewpoint framework │
│ • Map sections to viewpoints │
│ • Flag structural gaps │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 3: Coverage Verification │ ◀── Perfect Recall techniques
│ • Check 188 checklist items │ completeness_verification
│ • Record presence and quality │ consistency_check
│ • Cite evidence locations │ negative_space_analysis
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 4: Quality Attributes │ ◀── ISO 25010 validation
│ • Map to 8 quality attributes │
│ • Assess coverage level │
│ • Flag quality gaps │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 5: Debt & Anti-Patterns │ ◀── RUBRIC-07 severity scoring
│ • Classify gaps (6 types) │
│ • Score severity (3 dimensions) │
│ • Scan 25 anti-patterns │
│ • Detect 25+ debt indicators │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Phase 6: Synthesis │ ◀── CONTRACT-07 + Health Score
│ • Compile GAP-INVENTORY │
│ • Calculate Architecture Health │
│ • Generate remediation roadmap │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ OUTPUT: GAP-INVENTORY │
│ + Architecture Health Score │
│ + Technical Debt Roadmap │
└─────────────────────────────────────┘
| This Skill Produces | Consumed By |
|---|---|
| GAP-INVENTORY (CONTRACT-07) | Architecture review board, governance |
| Architecture Health Score | Executive reporting, readiness gates |
| Debt Remediation Roadmap | Technical leadership, sprint planning |
| Upstream | This Skill | Downstream |
|---|---|---|
| Architecture authoring | Audit | Implementation |
| ADR creation | Validate | Development sprint |
| C4 diagram creation | Check completeness | Technical design |
| Design doc drafting | Quality gate | Governance approval |
| File | Purpose |
|---|---|
references/architecture-standards.md | TOGAF, C4, arc42, IEEE 42010 frameworks |
references/architecture-checklist.md | 188 checklist items organized by viewpoint |
references/viewpoint-catalog.md | 14 viewpoint definitions with concerns |
references/quality-attributes.md | ISO 25010 quality model with validation |
references/technical-debt-indicators.md | 25+ debt signals with detection |
references/anti-patterns-catalog.md | 25 architecture anti-patterns |
references/compliance-frameworks.md | SOC2, GDPR, PCI-DSS requirements |
| File | Purpose |
|---|---|
@core/artifact-contracts.yaml | CONTRACT-07 (GAP-INVENTORY) schema |
@core/scoring-rubrics.yaml | RUBRIC-07 (SEVERITY-SCORING) specification |
@core/technique-taxonomy.yaml | Perfect Recall techniques (CAT-PR-GA) |
@core/skill-patterns.yaml | GAP-AUDIT pattern (PATTERN-08) |
| File | Purpose |
|---|---|
templates/gap-inventory-output.md | CONTRACT-07 compliant XML template with architecture extensions |
templates/architecture-health-report.md | Executive dashboard with viewpoint scores |
templates/debt-remediation-roadmap.md | Prioritized technical debt paydown plan |
input:
document: "[ADR-047: Adopt Event-Driven Architecture for Order Processing]"
document_type: adr
framework: auto
audit_depth: standard
include_anti_patterns: true
flow:
phase_1:
- Framework: Custom (MADR-like structure detected)
- Loaded ADR-focused checklist (V10: 20 items)
- Parsed: Title, Status, Context, Decision, Consequences
phase_2:
- Primary viewpoint: V10 (Decision Record)
- Secondary viewpoints assessed: V2 (Container), V6 (Integration)
- Structural gap: No explicit alternatives section
phase_3:
- Verified 20 ADR items + 15 related items
- 28 PRESENT + CLEAR
- 4 PARTIAL
- 3 ABSENT
phase_4:
- Quality attributes: Performance EXPLICIT, Scalability IMPLICIT, Reliability MISSING
phase_5:
- 7 gaps classified
- 0 CRITICAL
- 2 HIGH: Missing rollback strategy (V10-15), No SLO impact assessment (V10-18)
- 3 MEDIUM: Vague consequences (V10-10), Missing stakeholder sign-off (V10-20)
- 2 LOW: No review date (V10-19)
- Anti-patterns: AA-10 (partial - alternatives not documented)
phase_6:
- Architecture Health Score: 72 (ADEQUATE)
- ADR ready with minor gaps
output:
total_gaps: 7
by_severity: { critical: 0, high: 2, medium: 3, low: 2 }
health_score: 72
health_status: ADEQUATE
overall_assessment: minor_issues
recommendation: "Address rollback strategy and SLO impact before implementation."
input:
document: "[System Context Diagram + Description for Payment Gateway]"
document_type: system_context
framework: c4
audit_depth: standard
viewpoints: [V1, V6, V7]
flow:
phase_1:
- Framework: C4 (Level 1 - System Context)
- Loaded Context-focused checklist (52 items)
- Parsed: Diagram, external actors, integrations
phase_2:
- V1 (Context): Full coverage
- V6 (Integration): Partial coverage
- V7 (Security): Minimal coverage
- Structural gap: Trust boundaries not defined
phase_3:
- Verified 52 items
- 38 PRESENT
- 8 PARTIAL
- 6 ABSENT
phase_4:
- Security: MISSING (trust boundaries undefined)
- Interoperability: EXPLICIT
- Reliability: IMPLICIT
phase_5:
- 14 gaps classified
- 2 CRITICAL: No trust boundaries (V1-09), External auth flow missing (V7-01)
- 4 HIGH: SLA dependencies undocumented (V1-13), API versioning unclear (V6-05)
- 5 MEDIUM
- 3 LOW
- Anti-patterns: AA-22 (Trust Assumption)
phase_6:
- Architecture Health Score: 58 (AT_RISK)
- C4 Level 1 incomplete for security context
output:
total_gaps: 14
by_severity: { critical: 2, high: 4, medium: 5, low: 3 }
health_score: 58
health_status: AT_RISK
c4_maturity: { level_1_complete: false }
blocking_issues: 2
overall_assessment: significant_gaps
recommendation: "CRITICAL: Define trust boundaries and external auth flows before container design."
input:
document: "[Design Doc: Inventory Management Service Redesign - 12,000 words]"
document_type: design_doc
framework: arc42
audit_depth: exhaustive
include_debt_assessment: true
governance_context: enterprise
flow:
phase_1:
- Framework: arc42 (11 of 12 sections present)
- Loaded full checklist (188 items)
- Parsed: 24 sections, 8 diagrams, 5 ADRs inline
phase_2:
- All 10 core viewpoints assessed
- Conditional V11 (Multi-tenancy) applicable
- V8 (Operations) weakest coverage
- V10 (Decisions) strong with 5 ADRs
phase_3:
- Verified 188 items
- 142 PRESENT
- 28 PARTIAL
- 18 ABSENT
phase_4:
- All 8 quality attributes assessed
- Security: EXPLICIT
- Performance: EXPLICIT
- Reliability: IMPLICIT (needs SLOs)
- Operability: MISSING
phase_5:
- 46 gaps classified
- 1 CRITICAL: No disaster recovery strategy (V4-20)
- 8 HIGH: Missing monitoring strategy (V8-01), SLOs undefined (V8-05)
- 22 MEDIUM
- 15 LOW
- Anti-patterns: AA-17 (Observability Omission), AA-18 (SLO Silence)
- Technical debt: 8 indicators detected
- TD-D01: Diagrams >6 months stale
- TD-A03: No bounded contexts defined
- TD-I02: Manual deployment steps
phase_6:
- Architecture Health Score: 64 (ADEQUATE)
- Compliance gap: SOC2 monitoring requirements not met
output:
total_gaps: 46
by_severity: { critical: 1, high: 8, medium: 22, low: 15 }
anti_patterns_detected: 2
debt_indicators_detected: 8
health_score: 64
health_status: ADEQUATE
by_viewpoint:
V1: 2 gaps, V2: 4 gaps, V3: 3 gaps, V4: 6 gaps
V5: 4 gaps, V6: 5 gaps, V7: 3 gaps, V8: 12 gaps
V9: 4 gaps, V10: 2 gaps, V11: 1 gap
blocking_issues: 1
overall_assessment: significant_gaps
recommendation: "Address DR strategy (CRITICAL) and operability gaps before architecture review board."
debt_remediation:
immediate: ["DR strategy", "Monitoring strategy"]
short_term: ["SLO definition", "Deployment automation"]
medium_term: ["Diagram refresh", "Bounded context documentation"]
/architecture-doc-auditor
document: "[Paste architecture document or provide file path]"
document_type: design_doc
audit_depth: standard
npx claudepluginhub agentient/vibekit --plugin evaluation-toolsAudits single architecture element against ISO 26262-8 §6 axes (atomicity, traceability, etc.) plus arch-specific checks, emitting structured JSON findings with scores and action items.
Supplies critique dimensions for architecture quality reviews, detecting biases, validating ADRs, quality attributes, feasibility, and priorities in docs.
Performs systematic architecture reviews across 7 dimensions (structural, scalability, enterprise readiness, performance, security, ops, data) with scored reports and prioritized recommendations.