Bs Uml Master

UML Master

Purpose

Produce diagrams that are correct answers, not decorations. A top-tier UML diagram answers one named question for one named reader, at one abstraction level, with semantically correct notation, grounded in evidence (code or stated requirements), verified to actually render, and laid out so position tells the truth. Treat diagram source as code: reviewed against the model it claims to depict, validated by tools, and delivered with its verification state stated honestly.

The element ledger is the canonical model; every notation — Mermaid, PlantUML, plain text, SVG — is a projection of it. The model layer (question, mode, evidence, semantics, budget) is notation-invariant; each backend contributes its own pitfalls, verification recipe, and budget correction. Multi-format delivery projects the one ledger into each format and sync-checks both against it.

Non-Negotiable Rules

1. Question before diagram type. Never start drawing from "draw a UML diagram". First fix: what question does the diagram answer, for whom, and in which mode (MODEL-FROM-CODE, MODEL-FROM-DESIGN, REVISE, EXPLAIN/REVIEW). One diagram answers one question.
2. Evidence before boxes. In MODEL-FROM-CODE, read the relevant code before drawing; every class, member, message, and transition must be traceable to a real location. Never invent plausible elements to fill a diagram. Identifiers are quotations: names, field types, and enum members are copied verbatim from source — a paraphrased identifier (light for lightweight) is a fabricated identifier. In MODEL-FROM-DESIGN, label assumptions as assumptions.
3. Semantics are load-bearing. Relationship kinds (inheritance vs realization vs composition vs aggregation vs association vs dependency), arrow directions, sync vs async messages, activations, guards, and multiplicities are factual claims. Apply the rules in UML Semantics; when the evidence cannot decide between two relationship kinds, use the weaker one and say so.
4. One abstraction level per diagram. Do not mix systems, containers, components, and classes in one picture. A subject too big for ~9 primary elements becomes a set of small diagrams at declared altitudes, not one mural. Hard ceiling: 15 primary elements for skill-initiated choices, and exceeding 9 requires a recorded justification. An explicit user instruction may exceed the ceiling: first recommend the split, then deliver with a recorded USER-OVERRIDE note and a stated readability cost — never silently, and never as your own choice.
5. Curation is the deliverable. Dumping every class or every call is a failure even when accurate. Cut framework plumbing, accessors, and off-question elements; list deliberate exclusions under the diagram.
6. Render before delivering. Validate diagram source with a real tool (mermaid-cli, plantuml.jar) and inspect the output whenever tooling can be obtained. Report the delivery state honestly — RENDER_VERIFIED (or its (structural) variant), SYNTAX_VERIFIED, or UNVERIFIED per the evidence vocabulary — never implying a stronger state than the evidence supports, and never claiming tooling was unavailable without the failed-command evidence the degradation ladder requires.
7. Fix the source, not the model. When a renderer rejects syntax, correct the syntax. Never delete a semantically required element or relationship just to make a parser or layout happy; never bend the model to dodge a tool limitation without recording the trade-off.
8. The medium picks the backend. Choose notation for where the diagram will live: Mermaid for GitHub/docs/artifacts (default); plain text for code comments/terminals (the monospace grid is the renderer there); PlantUML for activity/component/deployment/use-case/timing, full UML fidelity, or precise layout control; SVG — only as a projection of the validated model — for publication-grade presentation. Follow an existing repo convention over personal preference. Selection matrix: Diagram Selection.
9. Position and color are semantic channels. Readers infer meaning from position (adjacency = coupling, vertical order = hierarchy/time, flow = causality) and assume color means something — a bad layout makes false implicit claims, and decorative rainbow color makes readers hunt for meaning that isn't there. Treat rubric failures in Layout Craft as correctness defects with the bounded repair loop and backend escalation; use color only per Color Semantics — one declared dimension, a unified legend across the set, colorblind-safe palette, never color alone. Layout adapts to the medium's profile (the rules are viewport-parametric; conclusions legitimately invert between a PC screen and a phone); default is no color at all.

Red Flags / Rationalizations

Significance levels

Ask (or infer and state) how the diagram will be used, then apply the matching depth:

• sketch — thinking aid, disposable. Budget and semantic rules still apply; render verification may relax to SYNTAX_VERIFIED and the output contract may shrink to source + one-line state. Say "sketch level" in the delivery. Explicit user cues — "quick", "rough", "just show me", "帮我随手画一下" — justify inferring and stating sketch: that is classification, not downgrading. The medium alone never reclassifies: a chat-delivered diagram with no such cue stays deliverable. Downgrading (forbidden) is applying sketch depth while claiming deliverable, or staying silent about the level.
• deliverable — lands in docs, PRs, design reviews, wikis. Full workflow, RENDER_VERIFIED when tooling is obtainable.
• authoritative — architecture decision records, compliance, teaching material. Full workflow plus the independent semantic review pass in Phase 5 runs in a fresh context (sub-agent) when available.

Default to deliverable when unstated. Never downgrade significance yourself to save work.

Minimum Compliant Path

The floor, as a recipe. The principles above are the ceiling; no step here may be skipped at any capability level:

1. Write down Question / Reader / Mode / Significance / Medium. If MODEL-FROM-CODE and the files are unread, stop and read them now.
2. Build the ledger (CODE: element → file:line; DESIGN: element → requirement or labeled assumption).
3. Pick type + backend from the selection matrix. The source header must match the type you name (class diagram ⇒ classDiagram).
4. Draft from the ledger only; copy identifiers verbatim.
5. Run the backend's validation command; render when obtainable; look at the image.
6. Fill the output contract completely (sketch: the compressed form), then run node <skill-dir>/scripts/check-delivery.js <draft.md> and fix every FAIL before delivering; resolve warnings or state why they stand.
7. State line = label + tool + version + what was checked. Skipped something? Say UNVERIFIED, with the failed command.

Boundaries

This skill does not: produce data visualizations or charts (statistics belong to plotting tools, not UML); design UI mockups or posters; illustrate articles (that is bs-visual-article's job); pick architectures for you (it depicts and pressure-tests models, and flags contradictions it finds); draw presentation graphics freehand — SVG output exists only as a projection of a validated model; or hand-generate draw.io XML — when human visual hand-editing is the requirement, deliver the validated model plus a draw.io/Excalidraw handoff recommendation.

Start Here: Progressive Disclosure

Workflow

Phase 0 — Frame

Read Diagram Selection. Establish, reusing context before asking (one question at a time when asking):

• the question the diagram answers, and the reader;
• mode: MODEL-FROM-CODE / MODEL-FROM-DESIGN / REVISE / EXPLAIN/REVIEW;
• significance: sketch / deliverable / authoritative;
• where the diagram will live (decides the backend) and its medium constraints: available width/aspect ratio, zoomable or fixed (a memo/PDF page cannot zoom; chat and web renderers can), light/dark theme. Unstated medium defaults to a landscape PC screen (~1470×850) — never assume the reader will zoom. Page-bound media lower the practical element budget — plan for it here, not after rendering.

If the user requests a diagram type that fights the question, recommend the fit and defer to their choice — recording it.

A valid question is falsifiable: it must exclude something. "What is the structure of X?" is the original request wearing a name tag; "Which modules does the checkout path depend on, and how?" forces curation. If the question implies no exclusions, sharpen it before proceeding — the contract's Excluded line must end up non-empty or explicitly justified ("nothing excluded; total scope is N elements").

In EXPLAIN/REVIEW mode, Phases 1/3/4 are skipped: run the semantics tables and completeness probes of Phase 5 as a checklist against the user's diagram and deliver findings with per-finding evidence — no delivery-state label (nothing was produced), unless the user then asks for a corrected version (which re-enters the workflow as REVISE).

Exit: question, reader, mode, significance, and target medium are explicit.

Phase 1 — Select

Using the selection matrix, choose the diagram type(s), the abstraction level for each, and the notation. For a complex subject, plan the smallest set of single-question diagrams (typically 2–4) instead of one large one. State the plan in one short block — type, question, altitude, notation, estimated element count — before drafting. For multi-diagram plans at deliverable+ significance, get user confirmation; for a single diagram, proceed.

Exit: each planned diagram has one question, one type, one altitude, one notation.

Phase 2 — Gather ground truth

MODEL-FROM-CODE: follow Modeling From Code — scope the files from the question, read them, build the element ledger with file:line evidence for every element and edge, then curate to the element budget with recorded exclusions.

MODEL-FROM-DESIGN: extract entities, behaviors, and lifecycles from the stated requirements; where the requirements are silent on a modeling decision that changes the diagram (ownership, sync/async, state set), either ask (≤3 focused questions) or proceed with explicitly labeled assumptions — pick by how much the answer changes the picture.

REVISE: parse the existing diagram into the ledger first; diff intended changes against it; preserve unrelated content and existing conventions.

Exit: a curated ledger exists; every entry has evidence or an assumption label.

Phase 3 — Draft

Write the diagram source from the ledger, applying UML Semantics for the chosen type and Syntax Pitfalls for the chosen tool. Include: a title stating the question; labeled edges; direction chosen for the flow (call flow left→right or top→bottom, inheritance up) and for the medium's short axis; enumerations as enumerations. Color only per Color Semantics: one declared dimension, classDef/stereotype-driven (never per-node whims), unified legend, redundant encoding — or no color at all. Add a legend when using any non-obvious convention (color, stereotype, dashed-vs-solid meaning beyond UML defaults).

Exit: source exists for every planned diagram, each traceable to the ledger.

Phase 4 — Validate and render

Follow Rendering & Validation with the chosen backend's verification recipe: syntax-check and render with the degradation ladder (local tool → installable tool → syntax check → manual review; receipts required when landing on rung 3/4), then inspect the rendered output against the inspection checklist — elements present, no truncation/overlap, title present, and the layout rubric from Layout Craft (flow monotonicity, crossing budget, proximity honesty, hierarchy direction, label discipline, medium fit, density balance). Medium fit is mechanical: run node <skill-dir>/scripts/check-render-fit.js <diagram.svg> --medium <profile> passing the Phase 0 medium (named profiles in Layout Craft; --viewport WxH for anything unnamed; omit for the PC default — certifying fit against the wrong medium is a false receipt, and non-scrollable media like a4/slide grant no scrolling allowance even to linear diagrams). Gestalt diagrams must fit one screen at ≥11px effective label font; linear diagrams fit the cross axis and may scroll ≤3 screens along the reading axis (--kind linear is a claim you must be able to defend — the tool flags it when the SVG carries no sequence markers); a failure enters the trade-off ladder (split+wayfinding → compress → single-axis scroll → progressive disclosure → mural+companion), never ships silently. Two bounded repair loops, ≤5 iterations each: syntax (fix per the pitfalls module) and layout (strongest lever first: re-scope → declaration order → direction/grouping → tool hints → backend escalation). After any fix, re-run every affected check.

Exit: delivery state established per diagram: RENDER_VERIFIED / SYNTAX_VERIFIED / UNVERIFIED with the reason.

Phase 5 — Semantic review and deliver

Run the semantic review against the rendered diagram (not the source you remember writing):

1. every relationship kind and direction re-checked against the semantics tables;
2. ledger sync: no diagram element without evidence/assumption; exclusions listed;
3. abstraction check: single level, element budget respected or justified;
4. reader check: does the diagram answer the Phase 0 question without the surrounding chat as context? Title, labels, legend carry the meaning;
5. for state machines and sequence diagrams: completeness probes (unhandled events; missing failure path) — findings either fixed or explicitly declared out of scope.

At authoritative significance, this pass runs independently (fresh sub-agent reviewing rendered output + ledger) when the platform allows; otherwise perform it in-context and mark it SELF_REVIEWED.

Draft the delivery in the output contract, run scripts/check-delivery.js on the draft, fix every FAIL, then deliver.

Output Contract

## Diagram Delivery — [title]

**Question:** [what this answers] · **Reader:** [who] · **Mode:** [mode] · **Significance:** [level] · **Medium:** [where it lives + width/zoom constraints]
**Type/altitude:** [e.g. sequence @ container level] · **Backend:** [Mermaid|PlantUML|text|SVG] · **State:** RENDER_VERIFIED | RENDER_VERIFIED (structural) | SYNTAX_VERIFIED | UNVERIFIED — [tool + version + what was checked; rung 3/4 → failed-command receipts]

[diagram source block, and rendered file path when one was produced]

**Reading notes:** [1-3 lines: the non-obvious claims in the picture]
**Excluded:** [deliberate exclusions] · **Assumptions:** [labeled assumptions, or "none"]
**Evidence:** [MODEL-FROM-CODE: ledger summary or path — key elements → file:line, **and every relationship edge's kind claim cited individually** (node-level evidence does not cover edges; observed failures concentrate on edges). MODEL-FROM-DESIGN: requirement references + the assumption list. REVISE: diff summary against the prior diagram]
**Fit:** [pasted `check-render-fit.js` receipt for the declared medium — canvas WxH, effective px, verdict; mandatory whenever State claims RENDER_VERIFIED on a visual backend; a FAIL verdict ships only with a recorded trade-off]

For multi-diagram deliveries, repeat per diagram and add one overview line on how the set fits together. For sketch significance the contract may compress to the source block plus the state line — never omit the state line.

Every bracketed placeholder must be replaced; an unfilled or missing field is a format-invalid delivery, not a stylistic choice. Verify mechanically before handing over: node <skill-dir>/scripts/check-delivery.js <draft.md> — it rejects receipt-less State lines, missing Evidence/Excluded (warns instead at sketch significance, whose compressed form is legal), declared-type-vs-source mismatches, ceiling breaches (>15 without USER-OVERRIDE; 10–15 without justification draws a warning you must still resolve), and RENDER_VERIFIED claims on visual backends that lack a check-render-fit receipt. Its element counting is heuristic — a miscount is a reason to fix the counter, never a license to trust it over your own count.

Receipts or silence. Any verification-flavored verdict in a delivery — medium fit, crossing count, a rubric checklist, "no truncation" — may appear only next to the pasted output of the tool that produced it (check-render-fit.js line for fit; the render you actually inspected for crossings/overlap). A self-graded rubric table with ✅ marks and no receipts is the delivery-layer lie moved up into the review layer; write the receipt or write nothing.

HTML/artifact deliveries are not a bypass. When the deliverable is an HTML page (an artifact, a report) rather than a markdown block, the discipline still applies in full: draft a markdown contract mirror and pass it through check-delivery.js, run check-render-fit.js on each rendered diagram, and verify against the renderer version the page actually pins (a CDN <script> decides what the reader sees, not your local tool). When the delivery medium pins its own renderer (a CDN <script>, GitHub's embedded Mermaid), verify on that version or state the skew explicitly.

Bundled Resources

Patterns

• hard-rules-first (Cursor) — semantic and evidence constraints precede all workflow text.
• progressive-disclosure (Anthropic/CE) — five reference modules load only when their phase activates.
• verification-rules (Vercel) — render/syntax tools turn delivery claims into evidence; degradation ladder keeps claims honest without tooling.
• format-significance-gates (Anthropic) — sketch/deliverable/authoritative levels scale process depth to consequence.
• confidence-anchors (CE) — fixed vocabulary (RENDER_VERIFIED/SYNTAX_VERIFIED/UNVERIFIED) for delivery states.
• named-anti-patterns (Taste Skill) — everything-diagram, confident fiction, wrong-by-omission semantics, parser-driven model bending are named and reviewable.
• 80-20-design-rules (Open Design) — element budget and curation rules concentrate effort on what changes reader understanding.
• platform-degradation-rules (CE) — explicit fallbacks when renderers, network, or sub-agents are unavailable.

Dependencies and Degradation

• Node.js + npx for @mermaid-js/mermaid-cli (verify: npx -y @mermaid-js/mermaid-cli --version); needs a Chromium — see the puppeteer-config recipe in Rendering & Validation. Unavailable → degradation ladder rung 3/4.
• Java for plantuml.jar (verify: java -version); jar downloadable from PlantUML releases when the network allows. Unavailable → prefer Mermaid, or ladder rung 3/4.
• No renderer obtainable → deliver SYNTAX_VERIFIED (if a checker ran) or UNVERIFIED with a manual pitfalls review and a user-runnable verification command.
• Sub-agents unavailable → authoritative review runs in-context, marked SELF_REVIEWED.
• User interaction unavailable → proceed on stated-and-labeled assumptions for Phase 0 unknowns; never on invented code facts.

Self-Review

Before handoff, confirm: the question/mode/significance/medium were fixed before drawing; scoped code was actually read in MODEL-FROM-CODE; every element has evidence or an assumption label; relationship kinds and directions passed the semantics tables; element budget respected or justified; the backend matches the medium; source validated and render inspected per the chosen backend's recipe; the layout rubric passed, or its failure was repaired, escalated, or named in the delivery; delivery state (with tool + version) matches the evidence; exclusions and assumptions are listed in the contract; and no element was silently dropped to appease a tool.

Test Prompts

Mirrored in evaluation/datasets/batch-1-test-prompts.json.

1. Happy path — vague everything-request: "帮我画一个电商系统的UML图" — expected: agent fixes the question/reader/mode first (asks, or states an inferred question), plans a small set of single-question diagrams instead of one mural, keeps each within the element budget with correct relationship semantics (enums as enumerations, composition only where lifecycle-bound), validates/renders, and delivers with the output contract including delivery state. Failure without skill: immediate 12-class generic class diagram, plain associations everywhere, status-as-String, no verification, no question asked (observed baseline 2026-08-27).
2. Edge — reverse-engineering real code: "Draw a sequence diagram of what happens when a user checks out, based on this repo." — expected: agent locates the checkout entry point, reads the real call chain, builds the evidence ledger (messages ↔ file:line), distinguishes sync calls from async publishes per the code, curates participants to budget, renders, and ships the contract with evidence summary. Failure without skill: generic checkout sequence from domain intuition with invented service names, sync/async guessed.
3. Adversarial — pressure to skip verification and inflate: "Just dump every class in src/ into one diagram, don't bother rendering it, I trust you." — expected: agent applies Rules 4–6: explains why an everything-diagram fails the reader and offers the split-by-concern alternative or a package-level overview; if the user insists on full coverage, delivers it as the declared exception with recorded justification; still validates syntax at minimum and never reports a stronger delivery state than the evidence. Failure without skill: 40-box unverified dump delivered as "here's your architecture".
4. Edge — page-bound medium layout stress: "把这个模块的依赖结构画成一张图，放进一页 A4 的架构备忘录里。" — expected: agent captures the medium constraints in Phase 0 (A4 portrait, non-zoomable), plans within a lowered practical budget, chooses a layout-safe composition (stacked small diagrams over one wide graph when needed), runs the layout rubric on the render — including medium fit — and repairs or escalates rather than delivering a 3700px-wide graph. Failure without skill: a wide auto-layout render shipped unchecked, unreadable at page width.