Draw JSON Architecture

Draw-JSON-architecture

One self-contained HTML Architecture Viewer per code flow, built from JSON in the surface's own folder. Walk the seven steps below in order, confirming with the user at each. No file is written until step 7. Long-form detail per step lives in prompts/.

Step 1 — Read the flow

If <flow> is missing, stop with: No flow provided. Re-run as /draw-json-architecture <flow>. Otherwise echo it back and let the user correct the framing. → prompts/01-read-flow.md

Step 2 — Name the surface

Derive a short kebab-case slug from the flow phrase — drop filler words, keep the meaningful nouns ("home screen to order placement" → home-to-order; "user signup" → user-signup). Confirm the folder it will create. → prompts/02-name-the-surface.md

Step 3 — Research the repo, propose stops + lenses

Walk the journey in code, entry to exit. Propose stops (each "thing that happens": page, handler, job, redirect) and lenses (one per dimension you actually saw — ui, database, api, llm, or surface-specific: cache, queue, webhook, …). Cite the file for every lens. Confirm; loop until settled.

Never propose a stop the code lacks. Never propose a lens you haven't seen. → prompts/03-research-the-flow.md

Step 4 — Pick a color per lens

For each confirmed lens, ask: "What color should <lens> paint?" Offer three CSS color names; user can override. Recap the palette and get one confirmation. → prompts/04-pick-colors.md

Step 5 — Confirm evidence flags per lens

An evidence flag is any non-happy-path fact the diagram should expose. Classify each as drift (diagram/code disagreement), risk (real runtime or correctness hazard), or assumption (intentional modeling choice). For each lens, propose 2–4 candidates from what you saw in step 3 — not a fixed list. User picks. → prompts/05-confirm-drift.md

Step 6 — Pick lens + mechanism per stop

Before writing the graph, decide each stop's primary lens (lens_selected) and call mechanism (type) together. Mechanism is constrained by lens — e.g. ui only accepts sequential (a page render arrives sync); api accepts all four (sequential, async, parallel, streaming). Use parallel only for a proven fan-out; if serial code is modeled as structural fan-out, record that as an assumption in reference.md. Walk the user through every stop and confirm both fields in one pass. → prompts/06-pick-mechanism.md

Step 7 — Author + build

Write source files under the configured source root (default architecture/<slug>/) using the lens+mechanism decided in step 6 (don't re-decide as you write), then run from the repo root:

1. node skills/draw-json-architecture/scripts/validate.mjs <slug> — structural check.
2. node <sourceRoot>/<slug>/assets/<slug>.test.mjs — surface truth-guard.
3. node skills/draw-json-architecture/scripts/audit-claims.mjs <slug> --strict — file/link/line/evidence/truth-guard audit.
4. node skills/draw-json-architecture/scripts/coverage.mjs <slug> --model "<model>" — coverage + meta-data refresh.
5. node skills/draw-json-architecture/scripts/builder.mjs <slug> — write the openable HTML.

Point the user at the builder output (default architecture/<slug>/<slug>.html). → prompts/07-author-the-surface.md

Rules

• Don't modify this skill's files while drawing a surface — surface-specific data lives in the surface's folder.
• Lens palette is per-surface. Validator + coverage read each surface's palette from its mapping.json; new lenses need zero skill edits.
• No hardcoded repo identity. The GitHub link base is auto-derived from git remote origin and the repo's default branch (origin/HEAD, else the checked-out branch); missing remote → plain paths.
• No unsupported claims. Any discrepancy.exist:true entry must have code evidence, a category (drift, risk, or assumption), and a truth-guard assertion or an explicit reason why it cannot be guarded.

Version

version: in this file's frontmatter is the only place the skill version is stored. Generated surfaces do not carry a skill version field.