diagram-design

name	diagram-design
description	Designs implementation-grounded architecture, sequence, and flow diagrams from existing code and documentation. Ensures notation is chosen intentionally, avoids invented components or flows, and explicitly flags mismatches across ADRs, RFCs, and code.
version	1.0.0
tags	["ui","architecture","diagram","design"]
resources	[]
vendor_support	{"claude":"native","opencode":"native","copilot":"prompt-inject","codex":"prompt-inject","gemini":"prompt-inject"}

Diagram Design Skill

Step 1 — Inspect Source of Truth

Inspect implementation artifacts before drawing:

• Code structure and runtime boundaries (modules, routes, services, adapters).
• Existing docs (README, ADRs, RFCs, architecture docs, API contracts).
• Current terminology used by the codebase and product language.

Capture what is explicitly evidenced. If evidence is missing, mark it as unknown.

Step 2 — Define Diagram Objective

State the single primary question the diagram must answer, such as:

• "How data moves from UI action to persistence."
• "Which components own state vs orchestration."
• "Where sync vs async boundaries are enforced."

Limit scope to one context per diagram to keep it reviewable.

Step 3 — Choose Notation Intentionally

Select notation based on the objective:

• C4/container or component view for structural ownership and dependencies.
• Sequence diagram for request/response timing and actor interactions.
• Flow/state diagram for decision branches, retries, and error handling.

Document why this notation was chosen and why alternatives were not.

Step 4 — Map Only Verified Components and Flows

Build the diagram strictly from verified artifacts:

• Use real component/service/module names from code/docs.
• Include only flows that can be traced to handlers, functions, contracts, or tests.
• Mark uncertain links as Unknown or TBD (needs evidence) instead of inventing paths.

Do not add speculative systems, side effects, queues, or external actors without evidence.

Step 5 — Cross-Check ADR/RFC/Code Consistency

Validate consistency across design intent and implementation:

• ADR says X, code does Y.
• RFC flow omits a runtime guard present in code.
• Code introduces dependency or sync call not reflected in docs.

List mismatches explicitly with:

• Source reference (ADR/RFC filename or code path).
• Observed conflict.
• Impact (correctness, performance, operability, ownership).

Step 6 — Deliver Diagram + Review Notes

Provide:

• The diagram artifact (Mermaid/PlantUML/ASCII/Figma structure as requested).
• A short legend for symbols and boundaries.
• Assumptions and unknowns.
• Mismatch log with recommended follow-up actions (doc update, ADR amendment, refactor).