/ln-25-architecture-diagram-builder

name: ln-25-architecture-diagram-builder
description: "Creates evidence-backed current or target architecture diagrams; not UI design."

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 checklist defines completion. Track each item internally as `PENDING`, `PROVEN` with evidence, `CLEARED` with evidence its condition is absent, or `UNPROVEN` with a gap; reading, delegation, or tool failure is not proof. Reconcile after each section. Before returning, resolve all `PENDING`, count only `PROVEN` and `CLEARED`, and apply verdict and approval rules to every gap. Preserve intent, scope, and existing authorization. Continue authorized work; ask only for consequential unresolved choices or required external approval. Scale depth to material risk without skipping checks. Preserve dependency and safety order; otherwise choose an appropriate verification method. Accept equivalent user or repository evidence; no other skill, named artifact, or complete lifecycle is required. Preserve source requirement and decision IDs. Bind reused evidence to relevant source versions, dirty changes, configuration, and environment; invalidate only affected claims. On continuation, reconcile task, authorization, current state, and unresolved evidence. For long work, return a compact continuation record or update an already authorized artifact; read-only skills do not persist it. Distinguish artifact readiness, verified behavior, and external-action authority. Prepare authorized work before required approval. If blocked by an instruction, cite its exact source and unresolved boundary; do not invent approval gates from caution.

Tool Routing

| Need | Preferred capability | Fallback | |---|---|---| | Architecture evidence | Repository files, runtime wiring, IaC, contracts, and approved artifacts | User-provided model with `UNVERIFIED` labels | | Relationship tracing | Language intelligence, dependency tools, and focused search | Direct inspection of producers, consumers, and registrations | | Diagram format | Existing repository convention and renderer | Mermaid in Markdown, then plain ASCII | | Syntax verification | Repository renderer, parser, or preview | Manual fence, identifier, and relationship inspection | | Document mutation | Minimal patch to approved diagram artifacts | Return `BLOCKED` if path or evidence boundary is unsafe |

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.

2. Build the Architecture Model

• [ ] Identify relevant people, systems, applications/data stores (C4 containers when using C4), components, queues, and external dependencies; distinguish logical containers from OS/container-runtime deployment units.
• [ ] Record responsibility, type, technology when decision-relevant, owner when known, and current/target status for each element.
• [ ] Resolve relationship direction, label, protocol or data, synchronicity, and trust or network boundary where relevant.
• [ ] Trace runtime discovery and registration before including current-state routes, handlers, jobs, plugins, or consumers.
• [ ] Mark uncertain elements or relationships `UNKNOWN` rather than completing the picture aesthetically.

3. Select and Draw Views

• [ ] Create a system-context view when readers need system scope and external actors.
• [ ] Create a container or deployment view for responsibilities, deployability, stores, or operational topology; include nodes, regions, networks, scaling, and failover when relevant to the audience question.
• [ ] Create a component view only for a complex area whose internal boundaries change understanding.
• [ ] Create sequence or dynamic views for critical success, failure, retry, timeout, recovery, or migration interactions.
• [ ] Create data-flow or trust-boundary views when security, privacy, residency, or system-of-record questions require them.
• [ ] Avoid mixing abstraction levels in one view unless the exception is explicit and necessary.

4. Make the Diagram Self-Describing

• [ ] Add title, diagram type, scope, current/target marker, intended audience, and observation or proposal date.
• [ ] Add a legend for shapes, colors, line styles, abbreviations, and uncert