Architectural Analysis Skill¶

Systematic methodology for analyzing and documenting unknown codebases.

Architecture Note¶

This skill is now a wrapper that combines: 1. codebase-analysis - Base analysis engine 2. architecture-docs - Output adapter

For alternative outputs (AGENTS.md, C4 models, etc.), see analysis-outputs.

Purpose¶

This skill enables comprehensive architectural analysis of unfamiliar codebases, producing accurate documentation with verifiable findings.

Core Principles¶

Documentation-First Verification¶

Every finding MUST be cross-referenced with existing documentation:

Check existing docs - Does documentation describe what we're finding?
Verify accuracy - Does the codebase match the documentation?
Flag discrepancies - Note where docs are missing, outdated, or incorrect

Output Structure¶

When invoked, this skill asks for a documentation directory and creates:

{docs-directory}/
└── architecture-docs/
    ├── index.md                              # Main entry point
    └── analysis/
        ├── 01-technology-manifest.md         # Languages, frameworks, dependencies
        ├── 02-interface-specification.md     # APIs, contracts, boundaries
        ├── 03-architecture-diagrams.md       # Visual system overview (Mermaid)
        ├── 04-documentation-audit.md         # Existing docs assessment
        ├── 05-dependency-health.md           # Security and maintenance status
        ├── 06-data-flow-map.md               # Data lifecycle and movement
        └── 07-error-handling.md              # Error patterns and recovery

The index.md serves as the main entry point with: - Executive summary of findings - Links to all analysis documents - Key recommendations - High-level architecture diagram

Diagram Format Options¶

During setup, you'll be asked to choose a diagram format:

Format	Best For
Mermaid (default)	GitHub, GitLab, modern markdown viewers
ASCII	Universal compatibility, terminal viewing
PlantUML	Complex diagrams, enterprise tooling

All diagrams in the output will use your chosen format consistently.

Excluded Files¶

The analysis automatically excludes AI agent configuration files: - AI toolkit submodule directory (e.g., .ai-toolkit/) - .aider/, .cursor/, .continue/ - AGENTS.md, CLAUDE.md, .cursorrules, .aider*

These contain agent instructions, not project architecture.

Analysis Outputs¶

Output	File	Description
Technology Manifest	`01-technology-manifest.md`	All languages, frameworks, libraries, tools
Interface Specification	`02-interface-specification.md`	All APIs, contracts, boundaries
Architecture Diagrams	`03-architecture-diagrams.md`	High-level system overview (Mermaid)
Documentation Audit	`04-documentation-audit.md`	Accuracy assessment of existing docs
Dependency Health	`05-dependency-health.md`	Vulnerability, maintenance, license status
Data Flow Map	`06-data-flow-map.md`	How data moves through the system
Error Handling	`07-error-handling.md`	Error patterns and recovery mechanisms

Invocation¶

This is an invokable skill. Activate with:

"Analyze the architecture of this codebase"

Or more specific variants: - "Map all the technologies used in this project" - "Find and document all interfaces" - "Create architecture diagrams for this system"

Analysis Philosophy¶

Depth-First Exploration¶

Don't skim - understand deeply before moving on: - Read entry points thoroughly - Trace execution paths - Understand data flow before documenting

Evidence-Based Documentation¶

Every claim must be traceable: - Cite specific files and line numbers - Include code snippets as evidence - Link findings to source locations

Assume Nothing¶

Don't trust file names alone
Don't assume standard conventions are followed
Verify everything against actual code

Key Concepts¶

Technology Stack¶

Categories to identify: - Languages: Primary and secondary languages used - Frameworks: Application frameworks (web, CLI, etc.) - Libraries: Dependencies and their purposes - Build Tools: Compilation, bundling, task runners - Infrastructure: Databases, caches, queues, cloud services - DevOps: CI/CD, containerization, deployment

Interfaces¶

Types to discover: - External APIs: REST, GraphQL, gRPC endpoints - Internal APIs: Service-to-service communication - Event Interfaces: Message queues, event buses - File Interfaces: Import/export formats - User Interfaces: CLI, GUI, web interfaces - Plugin/Extension: Extensibility points

Integration Patterns¶

Common patterns to identify: - Request/Response (synchronous) - Publish/Subscribe (asynchronous) - Event Sourcing - CQRS - Saga/Orchestration - Choreography

Success Criteria¶

A complete analysis includes: