Visual

/flow-next:visual restates one thing visually, in compact markdown, on one screen. Point it at a spec, a task, a git range, or the current conversation topic; the structure IS the output — you scan the shape, spot the wrong thing, and drill into only that file instead of reading everything to find out whether anything is wrong.

/flow-next:visual fn-42-add-oauth        # spec digest (post-plan review — the primary mode)
/flow-next:visual fn-42-add-oauth.3      # task digest
/flow-next:visual main..HEAD             # diff digest
/flow-next:visual                        # restate the current conversation topic

Or plain language on hosts that match skill descriptions (Claude Code, Cursor, Droid, Grok): “show me”, “too much text”, “walk me through the spec”, “explain this visually”. On Codex the digest is explicit-only ($flow-next-visual) — its trigger-rich description is deliberately kept out of the shared skill-catalog budget.

The middle register

Flow-Next has two visual registers: raw spec/task markdown and the opt-in HTML render lenses. This is the missing middle — zero machinery, renders natively in the terminal, in chat, and on every forge. Everything ships through plain fenced code blocks: diff fences colorize for free, text trees are monospace everywhere, ```ts signatures get highlighting for free. The richest-looking output is the cheapest one.

Why it exists

After /flow-next:plan, a reviewer faces the spec plus N task files — 500+ lines for a seven-task spec — and has to reconstruct the structure in their head by serial reading. The post-plan digest turns that into one screen: thesis, task tree, planned file layout, R-ID coverage, boundaries. Uncovered requirements jump out instead of requiring cross-referencing.

What a digest looks like

The real post-plan digest of the spec that shipped this skill:

Thesis: Flow-Next gains its missing middle visual register — a /flow-next:visual skill that restates specs, tasks, diffs, or the conversation as compact markdown, plus diff-fenced structural sketches in make-pr where mermaid is weakest.

fn-189 tasks (dependency order)
  .1 core skill + command shim        → SKILL.md, the 8-shape vocabulary
  ├─ .2 closer offers                 → one line each in capture/plan/interview
  ├─ .3 make-pr sketch license        → mermaid-rules §8
  └─ .4 platform + listing surfaces   → sync-codex, counts, CHANGELOG
     └─ .5 conduct + tests + dogfood  → checklist, prose-contract pins

plugins/flow-next/
|-- commands/
|   `-- visual.md                     # /flow-next:visual shim        (.1)
|-- skills/
|   |-- flow-next-visual/SKILL.md     # 8 shapes + 5 digest modes     (.1)
|   `-- flow-next-make-pr/
|       `-- mermaid-rules.md          # +§8 diff-fenced sketches      (.3)
|-- tests/
|   `-- test_visual_skill.py          # prose-contract pins           (.5)

Coverage: R1-R3 → .1 · R4 → .2 · R5 → .3 · R6,R7 → .4 · R8,R9 → .5 — none uncovered. IS: a markdown-only lens for review moments. IS-NOT: a replacement for the HTML lenses or a pipeline stage.

The shape vocabulary

Eight fixed shapes; the skill picks the smallest view that makes the key point clear and uses one or a few — never all:

Shape	Job
Pseudocode	logic or an algorithm
Call tree	runtime control flow, orchestration
Component tree	UI structure — only the hooks and boundaries that matter
Shallow file tree	”where does this live”, one responsibility per line
Diff-fenced structural sketch	the standout: diff syntax applied to a shape — what changes when the surrounding structure already exists
Types & signatures	the shape of code before any of it exists
Compact table	short enumerable facts only
Mermaid	last resort — sequence/state only, when a text shape can’t carry it

Every visual sits next to the one-or-two-sentence plain statement it supports; prose stays load-bearing.

Grounded, never invented

Every path in a file tree comes from a task file, the spec, or git diff --name-status; every call-tree edge traces to real code read in the session or a real task dependency; coverage lines come from the tasks’ declared satisfies frontmatter. No “for clarity” embellishment nodes — when in doubt, fewer nodes, more honest. The skill is read-only: chat output only, never writes, never mutates flow state.

Five digest modes

Target	Output
Spec (post-plan)	thesis · task tree · planned file-layout diff · shape sketch · R-ID coverage line · boundaries
Spec (pre-plan)	thesis · proposed shape · edge cases · boundaries
Task	what it produces, its position in the dependency tree, acceptance as 1-3 predicates
Diff range	file-layout diff with responsibilities, plus a structural sketch when the diff carries real structure
No id (ad-hoc)	restates the conversation topic or pasted text — the “too much text, show me” mode

Missing state degrades gracefully: no tasks yet → pre-plan digest; no spec → diff or ad-hoc; no flowctl at all → ad-hoc still works.

Where it’s offered

/flow-next:capture, /flow-next:plan, and /flow-next:interview each offer the digest at their read-back moment — one suggested-next-step line, an option you pick, never auto-run.

The same diff-fenced sketch shape also landed in /flow-next:make-pr’s ## Structural changes section: when mermaid’s collapse-to-one rule would fire, or a trigger fires marginally (a diagram under four nodes), the PR body may carry a diff-fenced file-tree or call-tree sketch instead — the same signal with zero silent-rendering-failure risk.

Click to zoom

The first shipped sketch — the PR that introduced this feature used it in place of an edge-less mermaid diagram. Click to zoom.