Validate Architecture Skill

Help developers create and maintain docs/c4/architecture-validated.md and docs/c4/validated/model.c4 - the human-validated goal for C4 generation improvement.

Related Skills

• effects-architecture: Provides M1-M4 documentation quality rules that apply to architecture documentation generation. See @plugins/devac/skills/effects-architecture/SKILL.md

Documentation Quality Standards

Before generating any architecture documentation, apply the M1-M4 meta-rules from effects-architecture:

Rule	Description	Application to C4
M1: Complete Sets	List ALL items or mark partial	List all containers, all relationships, all externals
M2: Generic Before Specific	Define abstractly before examples	Define what a "container" means before listing your containers
M3: State Recognition	Identify all state	Include all persistent stores (Parquet, DuckDB, etc.)
M4: Handler Recognition	Identify all transformers	Include components that transform data (Parsers, Analyzers)

See @plugins/devac/skills/effects-architecture/knowledge/quality-rules.md for full rule definitions.

Foundational Principle

From the Architecture Documentation Improvement Loop:

┌─────────────────────────────────────────────────────────────────────────┐
│                      IMPROVEMENT LOOP                                    │
│                                                                          │
│   validated/model.c4  ◄──── Human validates ◄──── Developer            │
│          (GOAL)                                                         │
│              │                                                          │
│              │ compare                                                  │
│              ▼                                                          │
│          GAP ────────────────────► effect-domain-rules                  │
│              ▲                            │                             │
│              │                            │ generate                    │
│   generated/model.c4  ◄──────────────────┘                             │
│         (GENERATED)                                                     │
└─────────────────────────────────────────────────────────────────────────┘

DO:

• Use devac MCP tools to analyze package structure
• Generate BOTH .md (comprehensive docs with diagrams) AND .c4 (LikeC4 DSL for comparison)
• Capture relationships explicitly with tables AND LikeC4 code blocks in the markdown
• Mark uncertain sections with ⚠️ and verified sections with ✓
• Create reasoning file documenting queries and assumptions
• Keep files in sync when making refinements

DON'T:

• Skip the reasoning file (it's the audit trail for improvement)
• Generate only one format (both are needed for the loop)
• Ignore external systems (they're key architectural elements)
• Encode relationships only in ASCII art - always add explicit tables and code blocks

Triggers

This skill activates when users ask about:

• "validate architecture"
• "create architecture documentation"
• "generate architecture-validated files"
• "update architecture"
• "check architecture drift"

Capabilities

Architecture Analysis

Analyze package to understand:

• Container Groupings: Logical layers (Analysis, Storage, Federation, etc.)
• Key Components: Architecturally-significant modules/classes
• Relationships: Data flow, dependencies, integration points
• External Systems: Databases, APIs, file systems, messaging

Document Generation

Generate documents in a separate directory to avoid LikeC4 merge conflicts:

• architecture-validated.md: Full docs with ASCII C4 diagrams, sequence diagrams, explanations
• validated/model.c4: LikeC4 DSL for structural comparison with generated .c4
• validated/spec.c4: Shared specification (copy from generated/spec.c4)
• validated/likec4.config.json: LikeC4 project config

Refinement Support

Accept refinement commands:

• "Move X to Y container"
• "Add relationship between A and B"
• "Mark external system Z as database type"
• "Group these components under Layer N"

Workflow

Step 1: Analyze Package

Use devac MCP tools to understand the package:

# Get high-level structure
devac query "SELECT DISTINCT kind, COUNT(*) as count FROM nodes WHERE package_id = 'devac-core' GROUP BY kind"

# Find key exported symbols
devac query "SELECT name, qualified_name, kind FROM nodes WHERE package_id = 'devac-core' AND is_exported = true ORDER BY name"

# Get effect patterns
devac effects list -p packages/devac-core --type Store
devac effects list -p packages/devac-core --type Send

Step 2: Generate Initial Files

Create documentation files in a separate directory to avoid LikeC4 merge conflicts:

CRITICAL: Relationship Parity by Construction

As you reason about each relationship for the ASCII diagram, immediately add it to:

1. A relationships table (human-readable)
2. A LikeC4 code block (machine-usable)

This ensures parity by construction rather than by validation. The model.c4 file is derived from concatenating the LikeC4 code blocks in the markdown.

• architecture-validated.md (at docs/c4/ root)

  • Overview section (✓ verified from package.json/README)
  • C4 Context diagram (ASCII art)
  • Context Relationships section (table + LikeC4 code block)
  • C4 Container diagram (ASCII art, grouped by layer)
  • Container Relationships section (table + LikeC4 code block per layer)
  • Key Components per container
  • Sequence diagrams for important flows
  • External System integrations

• validated/model.c4 (LikeC4 model file)

  • NO specification block (use spec.c4 instead)
  • Model block with containers/components
  • Relationships copied from markdown LikeC4 code blocks
  • Views for different levels

• validated/spec.c4 (copy from generated/spec.c4)

  • Shared element kind definitions
  • Relationship type definitions

• validated/likec4.config.json

  {
    "$schema": "https://likec4.dev/schemas/config.json",
    "name": "{package}-validated",
    "title": "{Package} Architecture (Human-Validated)"
  }
  

Step 3: Create Reasoning File

Document the analysis in docs/c4/architecture.reasoning.md:

# Architecture Reasoning: @package/name

## Queries Used
- `SELECT ...` - Purpose: understand X
- `devac effects ...` - Purpose: find external integrations

## Inferences Made
- ⚠️ Grouped Parser modules into "Analysis Layer" based on naming pattern
- ✓ Identified DuckDB as storage from effect patterns

## Gaps in Data
- Could not determine relationship direction for X
- Missing metadata for internal module Y

## Assumptions
- Assumed "hub" module is part of Federation layer (needs validation)

Step 4: Validate with Developer

Present documents for review:

1. Show ASCII diagrams in .md for quick review
2. Suggest opening LikeC4 VS Code extension for .c4 visual review
3. Accept refinement requests
4. Update BOTH files in sync

Step 5: Mark Verified

When developer approves:

• Add verification marker to metadata
• Commit both files

CLI Commands

devac architecture status

Check if architecture documentation needs updating.

devac architecture status -p packages/devac-core
# Output: STALE - seed hash changed since last validation

devac architecture score

Calculate gap metrics between validated and generated.

devac architecture score -p packages/devac-core
# Output: Gap Score: 42% (Container F1: 35%, Relationship F1: 50%, ...)

# With rule analysis (shows grouping and significance breakdown)
devac architecture score -p packages/devac-core --with-rules

# Verbose output showing matched rules
devac architecture score -p packages/devac-core --with-rules -v

See C4 Quality Rules for metric definitions and targets.

devac architecture diff

Show structural differences between validated and generated.

devac architecture diff -p packages/devac-core
# Output: Missing containers: Federation Layer, Extra: Utils, Types, ...

MCP Tools (Used for Analysis)

query_sql

Execute SQL queries against the code graph.

query_sql("SELECT name, kind FROM nodes WHERE package_id = 'devac-core' AND is_exported")

find_symbol

Find a specific symbol by name.

find_symbol("analyzePackage")

get_call_graph

Get function call relationships.

get_call_graph("analyzePackage", depth: 2)

get_dependencies

Get package dependencies.

get_dependencies("packages/devac-core")

query_effects

Query extracted effects.

query_effects(package: "devac-core", type: "Store")

File Format: docs/c4/architecture-validated.md

The markdown serves as the single source of truth. After each ASCII diagram, include:

1. A relationships table for human readability
2. A LikeC4 code block for machine extraction

# DevAC Core Architecture

> **Package:** @pietgk/devac-core
> **Validated:** 2026-01-07
> **Status:** Verified ✓

## Overview ✓

DevAC Core is a federated code analysis engine...

## C4 Context Diagram

┌─────────────────────────────────────────────────────────────────┐ │ CONTEXT │ │ ┌─────────────┐ ┌──────────────────┐ │ │ │ Developer │─────────►│ DevAC Core │ │ │ │ [Person] │ queries │ [System] │ │ │ └─────────────┘ └──────────────────┘ │ │ │ │ │ ┌─────────┼─────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────────┐ ┌──────┐ ┌────────┐ │ │ │ Source │ │ File │ │Central │ │ │ │ Code │ │System│ │Hub │ │ │ └──────────┘ └──────┘ └────────┘ │ └─────────────────────────────────────────────────────────────────┘

### Context Relationships

| From | To | Label |
|------|-----|-------|
| Developer | DevAC Core | Uses for analysis |
| DevAC Core | Source Code | Reads |
| DevAC Core | File System | Reads/Writes Parquet |
| DevAC Core | Central Hub | Reads/Writes |

```likec4
// Context relationships
developer -> devac_core "Uses"
devac_core -> source_code "Reads"
devac_core -> filesystem "Reads/Writes Parquet"
devac_core -> central_hub_db "Reads/Writes"

C4 Container Diagram

┌─────────────────────────────────────────────────────────────────┐
│                    ANALYSIS LAYER ✓                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
│  │ Parsers  │◄─│ Analyzer │──►│ Semantic │                      │
│  └────┬─────┘  └──────────┘  └────┬─────┘                      │
│       │                           │                              │
│       ▼                           ▼                              │
│  Source Code                 Source Code                         │
├─────────────────────────────────────────────────────────────────┤
│                    STORAGE LAYER ✓                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
│  │ DuckDB   │◄─│  Seeds   │  │ Effects  │                      │
│  └──────────┘  └────┬─────┘  └──────────┘                      │
│                     │                                            │
│                     ▼                                            │
│                File System                                       │
└─────────────────────────────────────────────────────────────────┘

Analysis Layer Relationships

From	To	Label
Analyzer	Parsers	Calls for structural parsing
Analyzer	Semantic	Calls for resolution
Parsers	Source Code	Reads
Semantic	Source Code	Reads

// Analysis layer relationships
devac_core.analyzer -> devac_core.parsers "Calls for structural parsing"
devac_core.analyzer -> devac_core.semantic "Calls for resolution"
devac_core.parsers -> source_code "Reads"
devac_core.semantic -> source_code "Reads"

Storage Layer Relationships

From	To	Label
Analyzer	Storage	Writes results
Storage	File System	Reads/Writes Parquet
Seeds	DuckDB	Queries via

// Storage layer relationships
devac_core.analyzer -> devac_core.storage "Writes results"
devac_core.storage -> filesystem "Reads/Writes Parquet"
devac_core.storage.seeds -> devac_core.storage.duckdb_pool "Queries via"

Key Components

Analysis Layer ✓

• Parsers: TS/Py/C# AST extraction (<50ms/file)
• Semantic: Cross-file resolution (50-200ms/file)
• Analyzer: Orchestrates analysis flow

Storage Layer ✓

• DuckDBPool: Connection pooling, error recovery
• SeedWriter/Reader: Parquet I/O to .devac/seed/
• EffectWriter/Reader: v3.0 foundation effect storage

Federation Layer ⚠️

• Central Hub: Cross-repo queries, Single Writer
• Workspace Manager: Multi-repo operations
• Context Discovery: Sibling repos, issue worktrees

External Systems ✓

System	Type	Technology
Source Code	Input	TS/Py/C# files
File System	Storage	Parquet seeds
Central Hub	Federation	DuckDB

All Relationships Summary

This section consolidates all relationships for easy model.c4 generation:

// =====================================================
// ALL RELATIONSHIPS (copy to model.c4)
// =====================================================

// Context level
developer -> devac_core "Uses"
devac_core -> source_code "Reads"
devac_core -> filesystem "Reads/Writes Parquet"
devac_core -> central_hub_db "Reads/Writes"

// Analysis layer
devac_core.analyzer -> devac_core.parsers "Calls for structural parsing"
devac_core.analyzer -> devac_core.semantic "Calls for resolution"
devac_core.parsers -> source_code "Reads"
devac_core.semantic -> source_code "Reads"

// Storage layer
devac_core.analyzer -> devac_core.storage "Writes results"
devac_core.storage -> filesystem "Reads/Writes Parquet"

## File Format: `docs/c4/validated/model.c4`

The `model.c4` file is **derived from the markdown** by:
1. Defining elements (containers, components, external systems)
2. **Copying relationships from the "All Relationships Summary" code block** in the markdown

```likec4
// validated/model.c4
// Human-validated architecture for gap comparison
// devac:validated: true
// devac:validated-at: 2026-01-07
// devac:package-path: packages/devac-core

model {
  devac_core = system 'DevAC Core' {
    description 'Federated code analysis engine'

    analyzer = container 'Analyzer' {
      description 'Orchestrates analysis flow'
    }

    parsers = container 'Parsers' {
      description 'TS/Py/C# AST extraction'
    }

    semantic = container 'Semantic' {
      description 'Cross-file resolution'
    }

    storage = container 'Storage Layer' {
      duckdb_pool = component 'DuckDBPool' {
        description 'Connection pooling'
      }
      seeds = component 'Seeds' {
        description 'Parquet I/O'
      }
    }
  }

  // External systems
  source_code = external_system 'Source Code' {
    description 'TS/Py/C# files'
  }
  filesystem = external_system 'File System' {
    description 'Parquet storage'
  }

  // =====================================================
  // RELATIONSHIPS (copied from architecture-validated.md)
  // =====================================================

  // Context level
  developer -> devac_core "Uses"
  devac_core -> source_code "Reads"
  devac_core -> filesystem "Reads/Writes Parquet"

  // Analysis layer
  devac_core.analyzer -> devac_core.parsers "Calls for structural parsing"
  devac_core.analyzer -> devac_core.semantic "Calls for resolution"
  devac_core.parsers -> source_code "Reads"
  devac_core.semantic -> source_code "Reads"

  // Storage layer
  devac_core.analyzer -> devac_core.storage "Writes results"
  devac_core.storage -> filesystem "Reads/Writes Parquet"
  devac_core.storage.seeds -> devac_core.storage.duckdb_pool "Queries via"
}

views {
  view containers of devac_core {
    title 'DevAC Core Containers'
    include *
    autoLayout TopBottom
  }
}

Note: The spec.c4 file defines element kinds with notations (for the diagram legend) and relationship types (for visual distinction):

specification {
  // Element kinds
  element person {
    notation "Person"
    style {
      shape person
      color blue
    }
  }

  element system {
    notation "Software System"
    style {
      shape rectangle
      color indigo
    }
  }

  element container {
    notation "Container"
    style {
      shape rectangle
      color sky
    }
  }

  element component {
    notation "Component"
    style {
      shape rectangle
      color slate
    }
  }

  element external_system {
    notation "External System"
    style {
      shape rectangle
      color gray
    }
  }

  // Relationship kinds (notations not yet supported)
  relationship reads {
    color green
    line solid
  }

  relationship writes {
    color amber
    line solid
  }

  relationship calls {
    color sky
    line dashed
  }

  relationship queries {
    color indigo
    line dashed
  }

  relationship uses {
    color slate
    line dashed
  }

  relationship ipc {
    color secondary
    line dotted
  }
}

Use typed relationships in model.c4: source -[reads]-> target "label"

Example Interaction

User: "Validate the architecture for packages/devac-core"

Response approach:

1. Query code graph for package structure
2. Identify containers (logical layers)
3. Find key components per container
4. Map external system interactions from effects
5. Generate architecture-validated.md with ASCII diagrams
6. Create validated/ directory with:
   • model.c4 (LikeC4 DSL, no specification block)
   • spec.c4 (copy from generated/)
   • likec4.config.json
7. Create architecture.reasoning.md documenting analysis
8. Present for developer review

User: "Move the Rules module into the Analysis Layer"

Response approach:

1. Update container assignment in .c4 model block
2. Update ASCII diagram in .md
3. Note the change in reasoning file
4. Re-present for validation

User: "Looks good, mark as verified"

Response approach:

1. Update status to "Verified ✓" in both files
2. Record validation timestamp
3. Commit files

Integration with Improvement Loop

After validation, the files enable:

# Calculate how close generated is to validated
devac architecture score -p packages/devac-core

# See what's missing/extra in generated
devac architecture diff -p packages/devac-core

# Regenerate .c4 and compare
devac c4 -p packages/devac-core
devac architecture score -p packages/devac-core

The gap score drives improvement of effect-domain-rules so that generated .c4 gets closer to validated .c4 over time.

LikeC4 Syntax Validation

CRITICAL: Always validate model.c4 before marking as complete.

# Validate the generated files
cd docs/c4/validated && npx likec4 validate .

If validation fails, fix the errors before proceeding. Common issues:

Reserved Keywords

These identifiers are reserved in LikeC4 and cannot be used as element names:

• views - Use diagram_views or view_layer instead
• model - Use data_model or model_layer instead
• specification - Use spec_layer instead

Syntax Errors

• Missing closing braces }
• Incorrect relationship syntax (must be source -> target "label")
• Invalid characters in identifiers (use snake_case)

Knowledge Sources

Source	Purpose
@knowledge/c4-quality-rules.md	G1-G4 gap metrics for C4 quality
@knowledge/tacit-insights.md	C4-specific insights not in code
@../effects-architecture/knowledge/quality-rules.md	M1-M4 documentation quality rules (apply these!)
@examples/architecture/prompts.md	Prompt evolution for C4 generation
@examples/architecture/common-mistakes.md	Mistakes and fixes
@examples/architecture/gap-analysis-session.md	Annotated improvement session

Notes

• Markdown is the single source of truth - relationships in model.c4 are copied from markdown code blocks
• Always generate BOTH .md and validated/model.c4 together (keep in sync)
• Parity by construction: As you draw ASCII diagrams, immediately add relationships to tables AND code blocks
• Use confidence markers (✓ verified, ⚠️ uncertain) liberally
• The reasoning file is essential for the improvement loop
• Don't skip external systems - they're key architectural elements
• Works well with /define-effects skill (effects inform architecture)
• Target gap score: >65% (from ~28% baseline)
• Important: The validated/ directory must have its own spec.c4 and likec4.config.json to avoid LikeC4 merge conflicts with generated/
• Avoid reserved keywords: Don't use views, model, specification as element identifiers
• Apply M1-M4 before finalizing: Check quality-rules.md from effects-architecture before marking documentation as complete

Gap Analysis Workflow

Use the gap metrics to systematically improve C4 documentation quality.

Step 1: Baseline Assessment

# Get current gap metrics
devac architecture score -p packages/devac-core --with-rules

Review the output to understand:

• Composite Score: Overall quality (target: >65%)
• Container F1: Are logical layers recognized? (target: >70%)
• Signal-to-Noise: Are implementation details filtered? (target: >50%)
• Relationship F1: Are key data flows captured? (target: >60%)
• External F1: Are external systems categorized? (target: >70%)

Step 2: Identify Improvement Areas

Based on the gaps, prioritize:

Gap	Problem	Solution
Low Container F1	Too granular, no layer recognition	Add grouping rules
Low Signal/Noise	All functions shown, no filtering	Add significance rules
Low Relationship F1	Missing data flow edges	Enhance effect domain rules
Low External F1	Externals uncategorized	Add provider patterns

Step 3: Apply Rules

# Generate C4 with rule-based grouping
devac c4 -p packages/devac-core --grouping rules

# Or configure rules in package's .devac/config.json

Step 4: Measure Improvement

# Re-run score to measure impact
devac architecture score -p packages/devac-core --with-rules

# Compare before/after composite scores

Step 5: Iterate

Continue refining rules until:

• Composite score >65%
• All individual metrics meet targets
• Generated architecture matches validated structure

Quality Rules Reference

See C4 Quality Rules for:

• Gap metric definitions (G1-G4)
• Built-in grouping rules (6 layers)
• Built-in significance rules (4 levels)
• Example improvement sessions

See Documentation Quality Rules for:

• Meta-rules (M1-M4) that apply to all documentation generation

Relationship Parity Checklist

Before marking as validated, verify:

• All ASCII arrows have corresponding rows in relationships tables
• All table rows have corresponding LikeC4 code in code blocks
• All code blocks are consolidated in "All Relationships Summary" section
• model.c4 relationships section matches the summary code block exactly
• Count of relationships in tables = count in code blocks = count in model.c4
• LikeC4 validation passes: npx likec4 validate . returns no errors