AGENT SKILL

loom-visualization

Show comparisons, flows, decisions, states or reasoning chains as tables, ASCII or Mermaid in coding chat, including when a Loom station reports to the user (intent restatement, choices, acceptance test results); not Obsidian notes.

License 许可
MIT
所属仓库
kouko/loom-plugins
最近更新
2026-11-15
Stars
★ 0
Forks
0

01 前言 Front Matter

name
loom-visualization
description
Show comparisons, flows, decisions, states or reasoning chains as tables, ASCII or Mermaid in coding chat, including when a Loom station reports to the user (intent restatement, choices, acceptance test results); not Obsidian notes.

02 资源文件 44

03 SKILL.md 正文

Loom Visualization

Deliver local documents with actual absolute paths from the active worktree or external location, including in copyable instructions. For known local Markdown support, use the document's project-relative path as link text (external files: basename) and absolute targets; otherwise show full absolute paths. Enclose targets with spaces in angle brackets: [doc.md](</worktree name/doc.md>). Preserve bundled references, stored relative paths, quoted examples and incidental filenames.

Pick the right shape and form for information in a coding-harness conversation, so the reader gets a table or a diagram that actually displays in their client instead of prose or broken Mermaid source.

<skill-dir> is this skill's folder: ${CLAUDE_SKILL_DIR} on Claude Code; on any other host, the directory that holds this SKILL.md. Run every script as python3 <skill-dir>/scripts/<name>.py; all other paths below are relative to <skill-dir>. The scripts need only the Python standard library.

A one-line fact needs no table. Reach for this skill when the answer has a shape: options side by side, three or more steps, a branch, a lifecycle, a message exchange, a structure, dates, or numbers to compare.

Boundary

<!-- gate: loom-visualization.obsidian-boundary --> When the output is written to a file, first run python3 <skill-dir>/scripts/detect_client.py --target <path>. Decline only when that --target check reports obsidian_vault: true, or when the user asks for a note in their Obsidian vault: say this skill serves coding-harness chat, and name obsidian:obsidian-mermaid-visualizer as the skill for vault notes. A chat answer proceeds normally even when the working directory is inside an Obsidian vault. Never put Obsidian-only syntax (wikilinks, callouts, %% comment lines) into anything this skill produces. <!-- /gate -->

Also out of scope: diagram rules for commit messages, pull requests and repository documents. Those follow the rules of the skill that owns the artifact (loom-workflow:git-memory, loom-code:ship, loom-design:write-spec).

Documented reasoning turned into a standalone page is page mode, below.

Plain language and conversation tables

These references sit beside the data-shape templates; the templates in Step 1 stay as they are.

Need Read
A plainer explanation, a decision question, or a table for a conversation situation (decision, before and after, progress, checklist, confirmed and unconfirmed, findings, risks, support matrix) references/plain-language.md
A software document: incident postmortem or incident report, test plan, traceability or compatibility matrix, migration guide, API parameters, runbook, RACI, ADR or RFC options, technology selection, feature-flag rollout, release notes, risk register, RAID log, threat model (STRIDE), decision table, state-transition table, truth table, morphological box, risk matrix, feature table, confusion matrix, correlation matrix references/tables-software.md
A design document: heuristic evaluation, usability test report, content audit, design critique, design tokens, component states, accessibility audit, journey map, personas or JTBD, design decision log references/tables-design.md
A business document: weighted or Pugh matrix, RICE, ICE, MoSCoW or WSJF, SWOT or TOWS, competitive analysis, Five Forces, stakeholder analysis, scenario planning, business case, OKR, assumption log, go/no-go, pricing tiers, Kano, decisional balance sheet, roadmap, 2×2 quadrants references/tables-business.md

Read only the one file whose row matches; a conversation-situation reply never opens a domain file.

Step 1 — Classify the information shape

Name the one shape the information has. If it has two, draw the one the reader must act on, and state the other in a sentence.

Shape Signals Template Generator
Option comparison 2+ options, shared criteria templates/01-option-comparison.md table
Linear steps 3+ steps, fixed order, no branch; before/after flows in titled panels templates/02-linear-steps.md flow
Branching decision a question sends work down different paths templates/03-branching-decision.md none
Reasoning chain causes or inferences leading to a conclusion templates/04-reasoning-chain.md none
State lifecycle named states changed by named events templates/05-state-lifecycle.md none
Actor sequence actors exchanging messages in time order templates/06-actor-sequence.md seq
Task dependencies parallel prerequisites feeding a required join templates/12-task-dependencies.md none
Cross-role workflow steps with different work ownership and handoffs templates/13-cross-role-workflow.md none
Hierarchy parent-child, no cross-links templates/07-hierarchy.md tree
System architecture components in layers with dependencies templates/08-system-architecture.md arch
Data model entities, fields, cardinality templates/09-data-model.md none (table substitute)
Timeline events on dates or periods templates/10-timeline.md none
Quantity a few labelled numbers to compare templates/11-quantity.md bar

Step 2 — Read only that template

Read the one template file from Step 1, and no other. Each template gives the shape's table form, ASCII form, Mermaid form and common mistakes, with a worked example to adapt.

Step 3 — Choose the form

Run python3 <skill-dir>/scripts/detect_client.py. It prints {client, mermaid, remote_viewer, obsidian_vault, reason}. What each client displays, with sources and a verified date, is in references/client-matrix.md.

<!-- gate: loom-visualization.mermaid-only-when-confirmed --> Use Mermaid only when you have no shell and your own host is claude.ai or the Claude Desktop chat, where Mermaid is reported to render. If you can run the client check at all, you have a shell, so do not use Mermaid. Everywhere else the reply gets a markdown table, which every client in the matrix renders. A drawn ASCII diagram goes in a fenced code block when the shape itself is the information, or when the answer is bound for a plain-text destination. A wrong Mermaid choice shows the user raw source; a markdown table reads everywhere. <!-- /gate -->

Which of the two forms to send:

  • Shaped content in a chat reply gets a markdown table by default; the drawn form is for a destination that does not render markdown, such as a code comment, a commit message or a plain-text file.
  • Option comparison always uses a GFM markdown table, in every client. Use the ASCII table generator only when the answer goes into a code block or a plain-text destination.
  • Data model and quantity need only the markdown table.
  • A flow, a branch, a reasoning chain, a state machine, a sequence, a hierarchy, an architecture, a timeline, task dependencies or a cross-role workflow may still be drawn in the reply when a table would lose what the reader needs: there the shape is the information. Draw it, verify it, and keep a table beside it when exact values matter.
  • The client never decides between the two. remote_viewer and the client name tell you whether Mermaid is safe, and nothing more.

Step 4 — Generate and verify the ASCII

Where the template names a generator, generate; do not hand-pad:

printf '%s' '<json input from the template>' | python3 <skill-dir>/scripts/generate.py <shape>

Shapes: table, flow, seq, tree, arch, bar. Pass the JSON as the printf '%s' argument so a \n inside a label reaches the script as a line break request rather than a raw newline. seq and bar labels must be single-line.

Where there is no generator (branching decision, reasoning chain, state lifecycle, timeline, task dependencies, cross-role workflow), adapt the template's ASCII by hand. The data model has no ASCII form; use its table substitute.

For how a node's text is structured and verified, see references/node-structure.md.

Always verify before sending:

printf '%s' '<your diagram>' | python3 <skill-dir>/scripts/align.py -

It prints a per-line width report, then either line N: col C: message for each drift or ✓ no drift, exiting 0 when clean and 1 on drift. Fix only the flagged lines and rerun until it is clean. The checks it runs are the vertical seam (scripts/checks_seam.py), table equal width (scripts/checks_table.py), kink plus arrowhead landing (scripts/checks_kink.py) and node structure (scripts/checks_nodes.py). The one exception is seq output: it is correct by construction, its blank off-span lifelines sit outside the seam model, and it is sent unedited.

Width rules the checks depend on:

  • Chinese and Japanese characters take two cells; the scripts measure this, so never count characters by eye.
  • Keep emoji and pictographic symbols out of box labels and table cells. Their width differs between terminals, so no check can make them align.
  • Keep ambiguous-width symbols (→, ★, ·, °, Greek letters) out of the column that sets a box's width. Use the generators' arrows (▼ ▲ ► ◄).

Page mode

Page mode turns reasoning that already exists (in a document, a folder, or this conversation) into one self-contained HTML page whose core is a chain-of-thought Mermaid diagram. It is for how a conclusion was reached, not for what a function does, and not for doing the thinking itself. The page is a file the user opens, so the chat client check does not apply to it.

Read references/page-mode.md in full before starting. It holds the whole procedure: resolve the source, extract the chain before drawing, build the diagram to references/mermaid-cot-spec.md, write the markdown from assets/cot-report-template.md, convert and verify, then run the fidelity check in references/fidelity-check.md before the page is shared.

Ask once whether the user wants an Artifact; do not publish unprompted, and never publish before the fidelity check passes.

Failure modes to refuse

  • Prose for a shaped answer. Three options described in paragraphs make the reader build the table themselves.
  • Mermaid "because it looks better". Outside a confirmed client the user sees raw source. The client check decides, not taste.
  • Hand-padded CJK boxes sent without scripts/align.py. Eyeballed widths break on the first full-width character.
  • Editing generator output by hand. Change the JSON input and regenerate.
  • A diagram for a trivial answer. Two steps or one fact is a sentence.
  • Reading every template "to be safe". Read the one the shape names.
  • Writing a vault note. Decline and name obsidian:obsidian-mermaid-visualizer.
  • A page drawn without reading the source, or padded to reach five nodes. Page mode's extraction is the work; three reasoning states get prose.
  • Unstructured multi-line box. A box interior with multiple content lines and no separator row — the node structure was skipped.
  • Empty separator. A separator row with no body line after it — the container rule was violated.

04 同仓库更多 Skills