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
- 最近更新
- 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
- 资产文件assets/cot-report-template.md4.5 KB
- 资产文件assets/trigger-card-coexist.md1.3 KB
- 资产文件assets/trigger-card.md1.2 KB
- 参考文档NOTICE.md2.3 KB
- 参考文档README.md1.8 KB
- 参考文档references/client-matrix.md3.0 KB
- 参考文档references/fidelity-check.md6.0 KB
- 参考文档references/mermaid-cot-spec.md18.2 KB
- 参考文档references/node-structure.md2.7 KB
- 参考文档references/page-mode.md18.9 KB
- 参考文档references/plain-language.md22.9 KB
- 参考文档references/tables-business.md16.8 KB
- 参考文档references/tables-design.md10.5 KB
- 参考文档references/tables-software.md22.7 KB
- 脚本scripts/align.py2.8 KB
- 脚本scripts/checks_kink.py6.6 KB
- 脚本scripts/checks_nodes.py7.7 KB
- 脚本scripts/checks_seam.py2.4 KB
- 脚本scripts/checks_table.py4.6 KB
- 脚本scripts/detect_client.py2.7 KB
- 脚本scripts/gen_arch.py11.3 KB
- 脚本scripts/gen_bar.py1.6 KB
- 脚本scripts/gen_flow.py7.4 KB
- 脚本scripts/gen_seq.py9.7 KB
- 脚本scripts/gen_table.py2.5 KB
- 脚本scripts/gen_tree.py3.2 KB
- 脚本scripts/generate.py2.8 KB
- 脚本scripts/glyphs.py1.0 KB
- 脚本scripts/render_cot_html.py43.9 KB
- 脚本scripts/verify_cot_html.py41.7 KB
- 脚本scripts/width.py8.6 KB
- 参考文档templates/01-option-comparison.md2.5 KB
- 参考文档templates/02-linear-steps.md7.5 KB
- 参考文档templates/03-branching-decision.md2.4 KB
- 参考文档templates/04-reasoning-chain.md3.9 KB
- 参考文档templates/05-state-lifecycle.md3.0 KB
- 参考文档templates/06-actor-sequence.md2.2 KB
- 参考文档templates/07-hierarchy.md1.6 KB
- 参考文档templates/08-system-architecture.md3.2 KB
- 参考文档templates/09-data-model.md1.6 KB
- 参考文档templates/10-timeline.md1.4 KB
- 参考文档templates/11-quantity.md1.2 KB
- 参考文档templates/12-task-dependencies.md1.9 KB
- 参考文档templates/13-cross-role-workflow.md1.9 KB
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_viewerand 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
using-loom-workflow
Route broad Loom workflow-tool requests to the right skill. Use when the request spans tools or the right workflow skill is unclear.
skill-retro
Review selected past or current Claude Code or Codex sessions against readable target skill sources and related integration. Produce source-linked proposals without applying changes.
recap-state
Give an in-session recap of current progress for 'where were we', '我們剛剛在幹嘛', '剛剛講到哪', '我跟丟了', 'ちょっと振り返って', '今どこだっけ', or '振り返り'. The built-in /recap is an away-summary.
project-retro
Review one current or specified coding session for source-backed project development improvements. Use for a requested retrospective, including 振り返り seeking improvements; not for current-progress recaps or recurring skill mining.
loom-memory
Record repo-wide lessons when saving to your own memory or asked to remember; recall, reconcile, or forget them when a task needs it.
loom-interactive-diagram
Create and check editable diagrams during standalone or Loom work. Use when the agent needs to create a diagram for the user to edit in an external editor or read back saved changes; draw.io is the default format.