spec-visualization
Produce a single-file interactive HTML dashboard visualizing a finalized spec — architectural planes, end-to-end pipeline (React Flow), wave timeline, review evolution, decisions, components, open gates. Self-contained, opens in browser, no build step. Trigger after spec-review fixes are applied, or on demand for any approved spec.
- License 许可
- MIT
- 所属仓库
- Roeelfs/keel
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- spec-visualization
- license
- MIT
- description
- Produce a single-file interactive HTML dashboard visualizing a finalized spec — architectural planes, end-to-end pipeline (React Flow), wave timeline, review evolution, decisions, components, open gates. Self-contained, opens in browser, no build step. Trigger after spec-review fixes are applied, or on demand for any approved spec.
02 资源文件 2
- 参考文档LEARNINGS.md1.4 KB
- 参考文档template.html27.9 KB
03 SKILL.md 正文
Spec Visualization
Produces a single HTML file that lets a reader grok an entire spec at a glance: the 4-plane data-boundary architecture, the commit→deploy pipeline as an interactive flow chart, wave-by-wave rollout with gating items, review evolution charts, decisions status, component inventory, open items dashboard.
When to invoke
- As Step 10 of
spec-review— after fixes are applied, before commit. Skip if spec is still Draft or no review files exist. - Standalone — when the user asks to "visualize the spec", "see the spec model", "render the design", or wants a fitness check against a vision.
- NOT for specs under 200 lines (overkill) or specs with no waves/reviews (the dashboard sections won't have data).
Output
<spec-path>.viz.html — single HTML file next to the spec. Opens in Chrome. Self-contained (CDN imports for React 18, @xyflow/react, Recharts, Tailwind, lucide-react, Babel standalone).
Process
Step 1: Locate inputs
- Spec file — the canonical .md (typically
docs/specs/active/YYYY-MM-DD-<name>.md) - Review files — any sibling
<spec-basename>.review*.mdfiles - Decisions doc — sibling
*-decisions.mdif present - Related platform specs — sibling specs referenced in the spec's frontmatter
If only the spec exists with no reviews/decisions, the dashboard renders with those sections empty — that's fine.
Step 2: Extract data into the canonical schema
Read the spec end-to-end. Map its content onto this canonical schema (the full field reference is defined inline below):
{
"meta": {
"title": "...", // from spec H1
"specPath": "docs/specs/active/...",
"version": "v0.3.1", // from "Status:" line
"issueRef": "#379", // from "Issue:" line
"branch": "spec/...", // git branch the spec lives on
"statusBadges": [ // array of {label, variant}
{"label": "v0.3.1", "variant": "accent"},
{"label": "Wave 1 ready", "variant": "success"}
],
"summary": "..." // 1-2 sentence top-of-page summary
},
"planes": [ // architectural layers, typically 3-5
{
"id": "workspace",
"label": "Plane 1 · Authoring",
"title": "Workspace",
"store": "Git repo · per project",
"desc": "Canonical multi-file source...",
"items": ["manifest.json", "schema.json", "..."],
"color": "violet", // violet | indigo | cyan | emerald | amber | rose
"icon": "GitBranch" // lucide-react icon name
}
],
"pipelineNodes": [ // React Flow nodes
{
"id": "agent",
"position": {"x": 0, "y": 0},
"data": {
"label": "Agent",
"sub": "build agent",
"plane": "workspace", // matches a plane id
"icon": "Sparkles"
}
}
],
"pipelineEdges": [ // React Flow edges
{
"id": "e1",
"source": "agent",
"target": "validate",
"label": "pushed", // optional
"animated": true, // optional
"color": "violet", // matches plane palette
"dashed": false // optional
}
],
"reviewRounds": [ // chronological
{"round": "v0.1", "critical": 7, "major": 14, "minor": 9, "verdict": "block"},
{"round": "v0.2", "critical": 10, "major": 18, "minor": 13, "verdict": "block"}
],
"waves": [ // rollout plan, typically from §17
{
"id": 0,
"title": "Spec + Model",
"state": "done", // done | next | pending
"ships": ["Spec finalized", "..."],
"gates": [
{"id": "NEW-NC7", "sev": "critical", "label": "I-1 amendment"},
{"id": "NEW-M2", "sev": "fixed", "label": "AND→OR"}
]
}
],
"decisions": [ // Wave 0 / open decisions
{
"id": "D1",
"topic": "Wave 5/6 ordering",
"flag": "NEW-NC8",
"rec": "Merge Wave 6 INTO Wave 5...",
"owner": "platform-architecture",
"status": "pending", // pending | updated | approved
"note": null // optional expanded note
}
],
"components": { // infra inventory grouped
"db": {
"label": "Database tables",
"count": "8 + 1 queue",
"icon": "Database",
"items": [
{"name": "project_repositories", "note": "one row per project · pointers + state"}
]
}
},
"openItemsByWave": [ // for stacked bar
{"wave": "W0", "critical": 1, "major": 0}
],
"boundaries": [ // data-store boundaries narrative
{
"color": "violet",
"label": "Git repo / object store",
"title": "Configuration",
"contents": "schema.json · automations · ..."
}
]
}
Extraction heuristics:
-
Planes — most specs have a "§4.1 Planes" or "Architecture" section with a table. If not, infer from the data-boundaries section. Typical specs have 3-4 planes mapping to data stores.
-
Pipeline nodes — read the "High-Level Flow" / sequence diagram / §X.Y materializer narrative. Each step becomes a node. Aim for 8-18 nodes — fewer than 8 is too sparse, more than 18 is overwhelming.
-
Pipeline edges — connect nodes in flow order. Color edges by source plane. Use
animated: truefor the critical happy path; static for diverging branches. Add labels for state transitions (e.g.,pushed,bundled,accepted). -
Pipeline layout — strict lane discipline (do this, not ad-hoc x/y). Overlapping edges are the #1 readability failure. React Flow uses
smoothstep(orthogonal) routing, so the layout must be planned as horizontal lanes:- Stride:
x+= 230 per pipeline stage (nodes are ~140-200px wide; 230 leaves a clean gap).ylanes ≥130px apart. - The spine is sacred. The happy path lives on one lane,
y: 0, strictly left-to-right. Nothing else may occupyy: 0, and no edge may route through they: 0band between two spine nodes except the spine edge itself. - Branches get their own lanes, never the spine. Parallel/alternative concerns (e.g. triage axes) → a vertical fan column at one shared
x, stacked aty: -180, -50, 80, 210. Recovery / safety / out-of-band → lower lanes (y: 300+), one lane per concern, running parallel to the spine then turning up into their join node — never diagonally across it. - Order branch endpoints to match. When several edges fan from one node to a column (or converge from a column into one node), order the targets vertically in the same order the edges leave/enter so lines don't cross each other.
- Feedback / backward edges (loops returning to an earlier stage) go on the lowest empty lane,
dashed: true, distinct color, with a label. Accept one clean long edge there; never route a backward edge through the spine or node bands. - Long-distance edges hug a lane. An edge spanning many stages must travel along an empty
ylane (its own), not cut diagonally. If two long edges would share a lane, give one a lane 130px lower. - Collapse before you lay out. Template nodes have a single left (target) / right (source) handle, so every off-spine edge loops around — N parallel sub-concerns rendered as N nodes produces N looping edges and guaranteed overlap. Model parallel/alternative concerns as one spine node with a summarizing
sub(e.g. "Three-axis triage · urgency · safety · statutory"); push the per-item detail into the Components section, not the flow. A flow chart shows flow, not every rule. Aim for a near-linear spine with ≤4 short off-spine edges + ≤2 isolated dashed lanes (one branch, one feedback). - Sanity check before render: every edge is either (a) a short spine hop, (b) a short confirm→{outputs,followup}-style stub, or (c) one of the ≤2 lane-hugging branch/feedback edges. Any edge that visually crosses a node = collapse nodes or relayout.
- Stride:
-
Review rounds — count CRITICAL/MAJOR/MINOR per
.review*.mdfile. The spec usually has a "review history" or change-log section with these counts. -
Waves — from §17 (or "Rollout Plan"). The "Must close before exit" subsections are the gates. Mark wave state:
done(status indicates done),next(the immediately-next wave),pending(everything later). -
Decisions — from any
*-decisions.mdcompanion. If none, omit the section. -
Components — from the spec's infrastructure sections: database tables, config/credential stores, inferred compute units (functions/services) from handler refs, encryption keys from the secrets section.
-
Open items by wave — count gating items in each wave by severity. Used for the stacked bar chart.
If the spec is too unstructured to extract any of these, drop the section from the data — the template renders gracefully with missing fields.
Step 3: Render
Copy template.html from this skill directory to <spec-path>.viz.html. Locate the <script id="spec-data" type="application/json"> block in the template and replace its inner text with the JSON-stringified data object from Step 2.
TEMPLATE="$HOME/.claude/skills/spec-visualization/template.html"
OUTPUT="${SPEC_PATH%.md}.viz.html"
# Read template, inject JSON data, write output. Use Python to avoid shell-escaping JSON:
python3 - "$TEMPLATE" "$OUTPUT" "$DATA_JSON_PATH" <<'PYEOF'
import sys, json, re
template = open(sys.argv[1]).read()
data = json.load(open(sys.argv[3]))
data_str = json.dumps(data, indent=2)
out = re.sub(
r'<script id="spec-data" type="application/json">[\s\S]*?</script>',
f'<script id="spec-data" type="application/json">{data_str}</script>',
template, count=1
)
open(sys.argv[2], 'w').write(out)
PYEOF
Step 4: Open + report
open -a "Google Chrome" "$OUTPUT"
Tell the user: file path, what sections rendered, any sections skipped (and why).
Step 5: Commit (optional)
If the spec is on a branch, offer to commit the .viz.html next to the spec:
git add "$OUTPUT"
git commit -m "docs(<scope>): visualize spec — interactive dashboard"
The .viz.html is reproducible from the spec, so committing is optional. If the spec is volatile (Draft early), don't commit.
Tips
- Layout the pipeline once — apply the strict lane discipline from the extraction heuristics (spine at
y:0, 230 x-stride, branches/feedback on their own lower lanes). Re-renders preserve positions; record finalx/yin the data. If any edge visually crosses a node after the first render, relayout — don't ship overlapping edges. - Wave count >8 — switch the wave timeline from horizontal to vertical lanes. Edit the template's wave-grid Tailwind class from
lg:grid-cols-8tolg:grid-cols-4for two rows. - No review history — drop the review evolution section entirely. The page is still informative without it.
- Light mode — the template is dark-only by design (operational dashboard aesthetic). Light mode adds complexity without payoff.
- Failure paths — color them rose. Use
dashed: trueon edges that represent recovery / out-of-band paths.
When NOT to use
- Specs without a clear architectural model (e.g., bug fixes, refactor specs) — the planes/pipeline sections won't have meaningful content
- One-shot reference docs (CLAUDE.md, runbooks) — those aren't specs
- Pre-Draft specs — the dashboard implies stability the spec hasn't reached
LEARNINGS.md
Append findings under What Worked / Patterns as you go. Specific entries worth saving: which extraction heuristic worked for a non-obvious spec shape, what makes a pipeline diagram readable, when to drop a section.
04 同仓库更多 Skills
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
work-report
Use when generating development reports, calculating billable hours, reviewing work done in a period, or when the user asks for a project status summary. Triggers on keywords like report, billable, hours, invoice, timesheet, work summary.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).