architecture-doc-auditor

What this skill does

# Architecture Documentation Auditor

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 Architecture Health Score extensions.

---

## 1. Purpose

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 |

---

## 2. When to Use

**Ideal for:**
- Architecture review gates before implementation
- ADR validation before development starts
- C4 diagram completeness verification
- Technical debt assessment and tracking
- Pre-implementation readiness check
- Governance and compliance audits
- Design document handoff to development teams
- Architecture decision board preparation
- System modernization planning
- Security architecture review

**Avoid when:**
- Document is code, not architecture (use code review)
- Operational runbook review (use operations auditor)
- Early ideation phase (architecture not yet defined)
- Quick clarifying questions (formal audit adds overhead)
- Infrastructure-as-Code review (use IaC auditor)
- API specification only (use API spec auditor)

---

## 3. Parameters

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

### Document Type Effects

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

### Audit Depth Effects

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

### Governance Context Effects

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

---

## 4. Six-Phase Workflow

### Phase 1: Document Intake & Framework Detection

**Purpose:** Load document and establish audit context.

**Steps:**
1. Receive architecture document (inline or file reference)
2. Detect architecture framework:
   - C4: Look for Context/Container/Component/Code levels
   - arc42: Look for 12-section template structure
   - TOGAF: Look for ADM phase artifacts
   - IEEE 42010: Look for formal viewpoint definitions
3. Load `architecture-checklist.md` reference
4. Calibrate checklist based on `document_type`:
   - Filter items by viewpoint applicability
   - Adjust severity levels for document type
   - Set critical items that must be present
5. Parse document to identify structure:
   - Extract section headers and hierarchy
   - Identify diagram references and types
   - Note ADRs (Architecture Decision Records)
   - Detect technology stack references
6. Load `viewpoint-catalog.md` for structural validation
7. Initialize gap tracking structure with empty findings

**Techniques Used:**
- `document_structure_extraction` - Parse document hierarchy
- `framework_detection` - Identify architecture methodology
- `checklist_calibration` - Adjust criteria for context

**Quality Gate:** Framework identified; checklist calibrated for document type; structure parsed with sections identified

**Output:** Calibrated checklist (N items) + Document structure map + Detected framework

---

### Phase 2: Viewpoint Mapping & Scope Definition

**Purpose:** Map document sections to architecture viewpoints and identify structural gaps.

**Steps:**
1. Load viewpoint framework from `viewpoint-catalog.md`:

   **Core Viewpoints (Always Assess):**
   - V1: Context & Scope (system boundary, external actors)
   - V2: Container Architecture (major components, technology choices)
   - V3: Component Design (internal structure, interfaces)
   - V4: Deployment Topology (infrastructure, scaling)
   - V5: Data Architecture (data stores, flows, ownership)
   - V6: Integration & APIs (contracts, protocols, versioning)
   - V7: Security Architecture (auth, encryption, compliance)
   - V8: Operational Concerns (monitoring, SLOs, runbooks)
   - V9: Cross-Cutting Concerns (logging, caching, config)
   - V10: Decision Record (ADRs, rationale, consequences)

   **Conditional Viewpoints (If Applicable):**
   - V11: Multi-tenancy (SaaS/multi-tenant systems)
   - V12: Event Architecture (event-driven systems)
   - V13: Migration Path (legacy modernization)
   - V14: Compliance Matrix (regulated industries)

2. Map each document section to viewpoints:
   - Assign based on content, not just header
   - Flag orphan sections (don't fit any viewpoint)
   - Flag missing viewpoints (no sections mapped)
3. Identify structural gaps:
   - Core viewpoint with no coverage = CRITICAL structural gap
   - Core viewpoint with partial coverage = HIGH structural gap
   - Conditional viewpoint missing when applicable = MEDIUM gap
4. Check for applicable conditional viewpoints:
   - Multi-tenancy: Evidence of tenant-based requirements
   - Event architecture: E