EricTechPro/super-board / skills/visual
visual
VerifiedTurn the current work into one polished, self-contained HTML visual page — a recap of a branch's changes, a plan, a map of a folder, endpoint set, or architecture, or an interactive drill-down map of a skill pack or system (zoom, pan, click a node for details, double-click to open its inner view). Use when the user runs /visual or asks to visualise, picture, or visually recap a branch, PR, diff, plan, or part of a codebase, or to map a skill pack, its lanes, scripts, and hooks.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.4 KB |
| SKILL.md | skill md | 6.0 KB |
| THIRD_PARTY_NOTICES.md | markdown | 4.4 KB |
| assets/template.html | other | 214.6 KB |
| references/schema.md | markdown | 13.3 KB |
| references/sections.md | markdown | 3.8 KB |
| scripts/visual.py | script | 41.2 KB |
SKILL.md
View on GitHub---
name: visual
description: Turn the current work into one polished, self-contained HTML visual page — a recap of a branch's changes, a plan, a map of a folder, endpoint set, or architecture, or an interactive drill-down map of a skill pack or system (zoom, pan, click a node for details, double-click to open its inner view). Use when the user runs /visual or asks to visualise, picture, or visually recap a branch, PR, diff, plan, or part of a codebase, or to map a skill pack, its lanes, scripts, and hooks.
---
# /visual
One command, one page. You write a `data.json`; `scripts/visual.py render` injects it into `assets/template.html`, which draws everything inline (SVG diagrams, file map, diffs) with no build step and no runtime CDN. Paths below are relative to this skill's folder; run the script from inside the project being visualised.
## Pick the mode
An argument wins: `/visual recap [base]`, `/visual plan [file]`, `/visual map [skills-dir or map.json]`, `/visual <path or thing>` (explore).
With no argument, run `python3 scripts/visual.py detect` and take the first that holds:
1. A plan was drafted in this conversation and not yet built → **plan**, from that text.
2. `suggested` is `recap` (branch ahead of base, or uncommitted changes) → **recap**.
3. `planCandidates` is non-empty → **plan**, from the newest one.
4. Otherwise → **explore** the current folder.
Say the chosen mode and its source in one line, then keep going.
## Run it
1. **Gather.** Recap: `python3 scripts/visual.py facts [--base REF]`, then read `git diff <mergeBase>` once, in order, taking notes; scope is the whole work unit of this conversation. Plan: read the plan and the real files it names. Explore: read the target; hand wide sweeps to a sub-agent.
2. **Write `data.json`** in the scratchpad, following `references/schema.md` and the section bar in `references/sections.md`.
3. **Render:** `python3 scripts/visual.py render data.json`. It prints `{"out", "bytes", "missingHunks", "check"}` and opens the page. Fix each missing hunk (wrong path or `contains`) and re-render.
4. **Check.** `render` runs `visual.py check` in headless Chrome: light and dark screenshots (plus one drilled-in view for a map), and an audit of every diagram or view: edge crossings, edges sharing a line, labels lying on a line or a node, and text overflowing its box (`check.counts`). Exit 2 means a problem: move nodes (`col`/`row`, or a view `layout`), cut edges a view does not need, shorten labels, and re-render. Read the PNGs it lists; a broken diagram or empty section means fix and re-render. `--no-check` skips it; `--shots DIR` picks where the PNGs go.
5. **Reply** with the path, the mode, and a 1–3 line gist. Offer to publish it as an Artifact (the page is fully inline); publish only on a yes.
## Map mode: a drill-down map
For a skill pack or any system with nested levels. The page is a clean flowchart, light first with a dark mode: one top bar (breadcrumbs, ⌘K search over nodes and views, theme, export, keys), a column browser of views on the left, the map in the middle, and a short details strip under it (header, then When to use · What it is · How it works · Example · Behind the scenes tabs). Wheel or pinch zooms, drag pans, the minimap moves the camera, a click opens the details, and double-click or Enter on a stacked node zooms into its inner view. Run-order views get swimlanes (Ask → Check → Fix → Finish …) when their parts name the phase. Breadcrumbs, Esc, and the browser back button go up; `#view=<id>&node=<id>` deep-links. On a phone the details become a bottom sheet.
1. **Skeleton.** `python3 scripts/visual.py skillmap <skills-dir> --deep --out map.json` reads SKILL.md frontmatter, `families.json`, `/skill` mentions, referenced scripts, and `hooks/settings-snippet.json`; `--deep` follows every external skill into the skills it triggers. Not a skill pack? Write `map.json` by hand.
2. **Enrich.** Read the skills and fill every node's `what`, `when`, `how`, and real `source` — the panel shows all four, so none stays empty. Main steps first: keep process views to roughly four to six columns, set `mainSteps: true`, and move scripts, state, and policies into a step’s child view. Every original node stays reachable. Hub views keep comb connectors. Mark outside skills `kind: external` with `author` (GitHub login) and add `authors`; `render` embeds their avatars. Fix edges and give each view a short `caption`. `references/schema.md` § Map model is the contract.
3. **Render:** `python3 scripts/visual.py render --map map.json`. It searches each view for a crossing-free layout and bakes it into the page, then runs the check. Publishing the page (GitHub Pages)? Add `--source-base https://github.com/OWNER/REPO/blob/main/` (and `--source-root <dir>` when the hosted repo is a subfolder) so Source links open the hosted file. Finish with steps 4–5 of Run it.
## Rules
- **Grounded:** in recap mode, files, `+/-`, and hunks come from git through `render` (`hunks[].file` + `contains`); hand-typed diff lines are for plan sketches only. Prose is the one free-text surface; label anything inferred as inferred.
- **Diagram first:** every page carries at least one diagram of the real mechanism — new endpoints, modules, data flow — with `change` flags on what moved. Columns follow the flow, rows hold peers.
- **Lean, not thin:** no boilerplate intro or "review the diff anyway" prose; every block says something specific about this change.
- **Secrets:** redact keys, tokens, and `.env` values in every block (`sk-•••`).
- **Plan is read-only:** make no source edits while planning.
- **Output** lands in a gitignored place: `_tmp/<date>-visual/` when the repo ignores `_tmp/`, else `.visual/` (self-ignoring). `--out` overrides.
## References
- `references/schema.md` — the `data.json` contract, diagram layout, and the map model; open before writing data.
- `references/sections.md` — per-mode section list and quality bar; open before writing data.
- `THIRD_PARTY_NOTICES.md` — Adapted from BuilderIO/skills (MIT); diagram style and viewer UX from tt-a1i/archify (MIT).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |