Architecture Diagram Builder

Architecture Diagram Builder

Goal: Create the smallest set of understandable, evidence-backed diagrams needed to communicate current or proposed architecture. Change only approved architecture documentation; do not invent relationships, perform visual product design, replace prose evidence, audit fitness, or edit implementation.

Execution contract: The ordered checkboxes are the Definition of Done. Track every item internally as PENDING, PROVEN with concrete evidence, CLEARED with evidence that its condition is absent, or UNPROVEN with a gap; reading, delegation, or tool failure is not proof. Reconcile items after each section. Before returning, resolve all PENDING and count only PROVEN and CLEARED; apply the skill's verdict and approval rules to every gap. Preserve user intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without silently skipping checks. Preserve dependency and safety ordering; otherwise choose the verification method appropriate to each obligation.

Tool Routing

Diagrams communicate a model; executable behavior remains authoritative for current state. Keep current, target, and transition views visibly distinct.

Artifact Rules

• Reuse an existing diagram convention or use docs/architecture/diagrams/<view>.md.
• Prefer Markdown with Mermaid for text-reviewable source; use ASCII when Mermaid is unsupported.
• For static structure, choose the context, container, or component level that answers the requested question; do not create prerequisite overview diagrams when existing context suffices.
• Keep diagram source reviewable in version control.
• Split views when one diagram needs multiple unrelated stories.
• Never use color as the only carrier of meaning.
• Use stable element identifiers and concise display labels so revisions produce reviewable diffs.
• Keep detailed evidence beside the diagram rather than crowding nodes and relationships.
• Preserve an understandable existing notation; introduce a new notation only when it answers the audience question better.

Checklist

1. Establish the Diagram Contract

• Resolve audience, question, current or target state, scope, approved destination, and required notation.
• Read repository instructions, relevant architecture artifacts, and existing diagram conventions.
• Select the minimum useful view or views; reject diagrams that add no relationship clarity.
• Define the evidence boundary and label user-supplied or proposed elements separately.
• Keep the run read-only except for approved architecture diagram documentation.