design-skills

Use whenever the user wants to record an architecture decision, create an ADR (Architecture Decision Record), capture WHY a specific technical choice was made, document a single architecturally-significant decision such as "documenta a decisão de usar Postgres em vez de MongoDB", "ADR pra escolha de message broker", "registra que escolhemos X em vez de Y", "capture this decision as an ADR", or any one-decision-per-document scenario in the Nygard/adr-tools tradition. Produces a numbered Markdown file (NNNN-kebab-slug.md) with 5 sections (Title, Date, Status, Context, Decision, Consequences) following Nygard canonical format. 1-2 pages, prose not bullets, active voice. Do NOT use for project-level design docs spanning multiple decisions (use design-doc skill), README files, postmortems, or specs.

Produces Structurizr DSL (.dsl) for C4 architecture diagrams (system context, container, and on explicit request component, dynamic, deployment, or system landscape views). Triggers when the user wants to draw, sketch, model, document, or visualize software architecture in the C4 tradition (Simon Brown), model microservices and queues at the right C4 level of abstraction, or work with Structurizr DSL. Output is Structurizr DSL ready to render with the user's preferred Structurizr tooling (online editor, local install, IDE plugin); default focus is system context and container levels, with component, dynamic, and deployment views only on explicit request or when complexity demands. Links ADRs via the !adrs directive when the project has them. Composes with the sequence-diagram skill (sequence diagrams are not C4 abstractions) and the design-doc skill (which has a C4 section that delegates here). Does NOT handle sequence diagrams, ER diagrams, flowcharts, class/UML diagrams, or non-architectural visualizations.

Use whenever the user wants to create or scaffold a design doc, TDD, RFC (project-level proposal), "documento de design", "documento técnico de projeto", "especificação técnica", "proposta técnica", or document a non-trivial multi-component system before implementation. Produces Markdown following a flat canon of 14 optional top-level sections (headers, overview, scope/context, goals/non-goals, solution, diagrams, APIs and payloads, screens, trade-offs, alternatives, cross-cutting concerns, testability/observability, deployment plan, open questions) — each independently optional with its own inclusion trigger. Delegates diagrams to sibling skills when available: c4-diagram (Structurizr DSL) and sequence-diagram (Mermaid). Includes collapsible payload tables for HTTP endpoints. Do NOT use for README files, API reference docs without design decisions behind them, postmortems, or single-decision ADRs like "documenta a decisão de X em vez de Y" — those are handled by the adr skill.

Use whenever the user wants to draw, sketch, model, or document a sequence diagram, an interaction between systems/services/components, the order of API calls, a request/response flow, an authentication handshake, an event-driven choreography, or any "who calls who" / "fluxo entre sistemas" / "diagrama de sequência" / "sequence diagram" scenario. Produces Mermaid sequenceDiagram syntax in a fenced mermaid code block that renders natively on GitHub/GitLab and, when the Mermaid MCP server is available, validates it with the real parser and returns a mermaid.live preview link. Do NOT use for sequencediagram.org or PlantUML notation, flowcharts, ER diagrams, class diagrams, state diagrams, deployment diagrams, or generic architecture diagrams.