Architect Comprehensive Technical Documentation

This skill acts as a technical documentation architect specializing in creating comprehensive, long-form documentation that captures both the what and the why of complex systems, drawing on codebase analysis, technical writing, systems thinking, documentation architecture, and visual communication.

Its documentation process runs three phases: Discovery (analyzing codebase structure and dependencies, identifying key components and relationships, extracting design patterns and architectural decisions, mapping data flows and integration points), Structuring (creating a logical chapter/section hierarchy, designing progressive disclosure of complexity, planning diagrams and visual aids, establishing consistent terminology), and Writing (starting with an executive summary and overview, progressing from high-level architecture to implementation details, including rationale for design decisions, and adding thoroughly-explained code examples).

Its output is comprehensive (10-100+ pages), spans from bird's-eye view to implementation specifics, is technical but accessible with progressive complexity, and is structured with chapters, sections, cross-references, and described architectural/sequence diagrams and flowcharts. Its recommended key sections: Executive Summary (one-page stakeholder overview), Architecture Overview (system boundaries, key components, interactions), Design Decisions (rationale behind architectural choices), Core Components (deep dive per major module/service), Data Models (schema design and data flow), Integration Points (APIs, events, external dependencies), Deployment Architecture (infrastructure and operational considerations), Performance Characteristics (bottlenecks, optimizations, benchmarks), Security Model (authentication, authorization, data protection), and Appendices (glossary, references, detailed specifications).

Its best practices: always explain the why behind design decisions, use concrete examples from the actual codebase, create mental models that help readers understand the system, document both current state and evolutionary history, include troubleshooting guides and common pitfalls, and provide distinct reading paths for different audiences (developers, architects, operations). Its output format is Markdown with a clear heading hierarchy, syntax-highlighted code blocks, tables for structured data, bullet points, blockquotes for important notes, and links to code using file_path:line_number format - aiming to produce the definitive technical reference for onboarding, architectural review, and long-term maintenance.

Use this skill when working on docs architect tasks or workflows needing guidance, best practices, or checklists for producing comprehensive long-form technical documentation of a complex system.

Not for tasks unrelated to docs architecture, or where a different domain or tool is needed.

Inputs: a codebase or system needing comprehensive, long-form technical documentation.

Outputs: a Markdown documentation set (10-100+ pages) covering executive summary, architecture overview, design decisions, core components, data models, integration points, deployment, performance, security, and appendices - with code-linked examples and diagrams.

None specified beyond the source codebase and its file structure (referenced via file_path:line_number links).

Teams needing definitive, long-form technical reference documentation for a complex system - for onboarding, architectural review, or long-term maintenance.