Generate Comprehensive System Design Documents

This skill turns the model into an expert system design document author, translating complex technical requirements into clear, actionable specifications that serve as blueprints for development teams, stakeholders, and future maintainers. It works from a fixed core structure: Executive Summary, Requirements Analysis, System Architecture, Detailed Design, Implementation Plan, Operational Considerations, and Risk Assessment.

For architecture documentation it produces C4-model component diagrams (rendered as Mermaid graphs showing load balancers, API servers, caches, and database replicas) and OpenAPI-style endpoint specifications with request bodies, validation rules, and response codes. For non-functional requirements it quantifies throughput, latency, availability, and scalability with concrete example metrics - such as handling 10,000 requests/second at peak, 95th-percentile API latency under 200ms, and 99.9% uptime (a maximum of 8.77 downtime hours per year) - alongside data volume projections covering daily active users, request volume, and storage growth.

On the database side it writes complete schema definitions with constraints and indexes, for example:

CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    last_login TIMESTAMP,
    status user_status_enum DEFAULT 'active',
    INDEX idx_email (email),
    INDEX idx_status_created (status, created_at)
);

plus data-flow diagrams tracing a request from client through API gateway, authentication, business logic, and into the database. It documents scalability patterns including multi-layer caching strategies (application memory, distributed cache, CDN) with invalidation rules, and load-balancer configuration. Security architecture output covers authentication flows (JWT tokens with short expiry plus longer-lived refresh tokens) and data protection measures: encryption at rest and in transit, role-based access control, and audit logging. Deployment sections include environment configuration for production databases, caches, and monitoring endpoints, plus concrete alerting thresholds for error rate, response time, and connection pool utilization. A Risk Assessment Matrix scores risks like database failure or security breach by probability and impact with named mitigations, and an Implementation Phases section breaks delivery into a multi-week phased plan.

Use this skill when you need a formal, stakeholder-ready design document before or during a non-trivial software build: a new service, a significant architectural change, or a project that needs sign-off from multiple teams. It is well suited to producing living documentation meant to be updated as the system evolves and to serve as the single source of truth for architectural decisions.

It is not the right tool for quick internal notes, a single function's implementation details, or documents that don't need the full seven-section structure - the output is deliberately comprehensive and can be more document than a small feature warrants.

Inputs are the technical requirements and constraints of the system being designed. Output is a structured Markdown design document following the seven-section hierarchy, populated with diagrams (Mermaid, data-flow ASCII), schema and configuration code blocks (SQL, YAML, nginx), a risk matrix table, and a phased implementation plan.

Software engineers, technical leads, and architects who need to produce or standardize system design documentation for engineering teams and stakeholders before implementation begins.