18 added, 28 removed. Audit A to A.
---
name: ln-75-architecture-diagram-builder
- description: "Creates evidence-backed current or target architecture diagrams when the diagram is the primary deliverable. Not for UI design, architecture audit, or invented structure."
+ description: "Creates current or target architecture diagrams as the primary deliverable. Not for UI design, architecture audits, or invented structure."
---
# 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:** Treat the ordered checkbox workflow below as this skill's Definition of Done. Track every checkbox as `PENDING`, then resolve it to `PROVEN` with concrete evidence, `CLEARED` with evidence that its conditional trigger is absent, or `UNPROVEN`; reading, mentioning, delegating, skipping, or tool failure is not proof.
- Before returning, resolve every `PENDING`, count only `PROVEN` and `CLEARED` items as complete, apply this skill's verdict, decision, and approval rules to every `UNPROVEN`, and prepend **Checklist: X/Y complete**<br>**Incomplete: None | section/item — reason; outcome impact; exact next action**; list every `UNPROVEN` item.
+ **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
| 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.
- - Choose only views that answer a named audience question.
- - For static structure, start with system context and container views; add component depth only when it changes a decision.
- - Use sequence or dynamic views for critical runtime interactions and failure paths.
- - Use data-flow views for stores, sensitive data, trust boundaries, and transformations.
- - Use deployment views for runtime nodes, regions, networks, scaling, and failover.
- - Give every diagram a title, scope, audience, legend, element descriptions, and labeled relationships.
+ - 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 people, software systems, deployable containers, components, stores, queues, and external dependencies relevant to the question.
+ - [ ] 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 when readers need responsibilities, deployability, stores, or operational topology.
+ - [ ] 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 uncertainty markers.
- [ ] Label every relationship with intent or data; avoid generic arrows and unexplained acronyms.
- [ ] Keep names consistent with code, contracts, and shared architecture documents.
- [ ] Add compact evidence notes or links sufficient to trace current-state claims.
### 5. Verify and Report
- [ ] Validate syntax with the repository renderer or perform a complete manual syntax inspection.
- - [ ] Check readability at normal rendering size and split overloaded views rather than shrinking labels.
- - [ ] Verify each current-state element and relationship against repository evidence.
- - [ ] Confirm no UI design, audit verdict, code, tests, or external state changed.
+ - [ ] Inspect rendered readability when a preview is available and split overloaded views rather than shrinking labels. Without a renderer, record visual readability as `UNPROVEN`; manual syntax inspection is not render proof.
+ - [ ] Verify current-state elements and relationships against implementation evidence, and target-state elements against the declared proposal or explicitly labelled assumptions.
- [ ] Use `READY` when diagrams are valid, scoped, and evidenced; use `INCONCLUSIVE` when material relationships remain unknown; use `BLOCKED` when scope, evidence, format, or destination prevents a trustworthy diagram.
- ## Output Contract
+ ## Self-Check
- ```markdown
- # Architecture Diagrams
+ - [ ] **Reconcile before returning.** Check item-level evidence, requirement coverage, contradictions, scope, verdict, and applicable cleanup. Correct the report or authorized artifacts. Reuse valid evidence; do not automatically rescan the repository or rerun successful commands. Repeat checks only for relevant changes, failures, or unresolved evidence. Disclose remaining gaps.
- **Verdict:** READY | INCONCLUSIVE | BLOCKED
- **Artifacts:** paths
+ ## Output Contract
- ## Views created or updated
- | View | State | Audience question | Evidence basis |
- |---|---|---|---|
+ Report in the user's language, in this order; retain all five fields and state each fact once. Small results may use one line per field; omit empty tables and do not copy linked artifacts:
- ## Verification
- - Syntax or render check
- - Current-state relationship checks
+ 1. **Result:** Skill-specific verdict and supported outcome.
+ 2. **Scope:** Reviewed/changed scope, exclusions, baseline, and material assumptions.
+ 3. **Evidence:** Skill-specific fields below; distinguish facts, inferences, and unverified claims. Link artifacts; use tables when useful.
+ 4. **Verification:** Checks/results, unavailable evidence, and applicable cleanup/external state.
+ 5. **Completion:** `Checklist: X/Y complete`; `Incomplete: None` or each `UNPROVEN` item's reason, outcome impact, and exact next action; residual risks and required decisions.
- ## Unknowns and residual risks
- Only missing relationships or rendering limits that affect interpretation.
- ```
+ **Skill-specific evidence:** Artifact paths; each view’s current/target state, audience question, and evidence basis. Report syntax/render verification and current-state relationship checks, unknown relationships, and rendering limits that affect interpretation.