/flow-next-visual

name: flow-next-visual
description: "Restate a spec, a task, a diff, or the current topic visually as a compact markdown digest. Use when asked to 'show me', 'explain this visually', 'restate that', 'digest the plan', 'walk me through the spec', 'walk me through the tasks', 'walk me through the diff', or when the output is too much text and a shape would land faster. Triggers on /flow-next:visual with an optional spec id, task id, git range, or free-form topic."
user-invocable: false
allowed-tools: Read, Bash, Grep, Glob

Visual — human-first markdown digest

Restate one thing visually, in compact markdown, on one screen. The structure IS the output: the reader scans the shape, spots the wrong thing, and drills into only that file instead of reading everything to find out whether anything is wrong.

**Output contract:** compact markdown visuals rendered in chat — fenced text/diff/code blocks and tiny tables. Never images, never HTML files, never a written artifact. Everything here renders natively in the terminal, in chat, and on every forge: ```diff fences color for free, ```text is monospace everywhere, ```ts gets highlighting for free. There is no rendering machinery — the shapes below are the whole product.

**Read-only.** This skill reads state and responds. It never writes files, never mutates flow state, never commits, never runs a workflow. (If the user asks to save a digest, that is an ordinary Write with ordinary consent — not a mode of this skill.)

Rich HTML render lenses are a different register and stay where they are (`artifacts.html.enabled`); this skill never produces or replaces them.

Preamble

flowctl is bundled with the plugin (not on PATH). Define once; subsequent blocks use `$FLOWCTL`:

FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"

Input

Arguments: `$ARGUMENTS` — optional. One of:

• **Spec id** (`fn-189-human-first-visual-digest-skill`) → spec digest
• **Task id** (`fn-189-human-first-visual-digest-skill.1`) → task digest
• **Git range** (`main..HEAD`, `abc123..def456`, or the bare word `diff`) → diff digest
• **Nothing, or free-form text** → ad-hoc restate of the current topic (or of the text pointed at)

Digest modes

Spec digest (post-plan) — the primary mode

Read `$FLOWCTL show <spec-id> --json`, the spec markdown (`$FLOWCTL cat <spec-id>`), and every task file (`$FLOWCTL cat <task-id>`). Emit these six elements, in order, on one screen:

1. **Thesis** — 1-2 sentences: what ships and why. 2. **Task tree** — indented text tree in dependency order, parallel groups adjacent; one line per task: id, short title, the one thing it produces. 3. **Planned file-layout diff** — shallow tree with `+` (new) / `~` (changed) per file or dir, one-line responsibility, owning task id annotated, so the reviewer sees where the change lands and who owns it. 4. **Shape sketch** — the new/changed types, signatures, config keys, or command surfaces the tasks will create (shape 6), when the plan implies any. Skip when it implies none. 5. **R-ID coverage line** — one compact line or tiny table from the tasks' declared `satisfies` arrays, which live in each task file's frontmatter (`$FLOWCTL cat <task-id>`), not in `show --json`: `R1 -> t1 · R2 -> t2,t3 · R5 -> UNCOVERED`. Uncovered and undeclared jump out instead of needing cross-referencing. 6. **Boundaries** — IS / IS-NOT, one line each side.

Spec digest (pre-plan)

No tasks yet: thesis, proposed shape, edge cases as one-liners, boundaries. No task tree, no coverage line — there is nothing to derive them from, and inventing them is the failure mode this mode exists to avoid.

Task digest

One task: what it produces (shape sketch or file-layout diff), its position in the dependency tree, and its acceptance restated as 1-3 predicates.

Diff digest

Input is a git range; on a branch with no range given, default to the merge base with the default branch (`git merge-base origin/HEAD HEAD` or the repo's default branch). Emit a file-layout diff with paths from `git diff --name-status` (rename-aware path identity — `--stat` prints `{old => new}` presentation labels, not paths) and churn from `git diff --stat`, plus a call-tree or component-tree sketch of the load-bearing structural change — when the diff carries one. A docs/config-only range with no real call or component relationship gets the grounded file-layout diff alone; never invent structure to satisfy the shape. For orienting a reader before they read the real diff. Empty range: say so in one line and stop — never fabricate a sketch.

Ad-hoc restate

No flow id: restate the current conversation topic, or the text the user points at, using the vocabulary. This is the "too much text — show me" mode and the natural-language entry point. Needs no flowctl and no git.

Grounding (hallucination guardrails)

• Every path in a file tree comes from a task file, the spec, or `git diff --name-status` — never invented. (`--stat` is for churn numbers only; its rename labels `{old => new}` are presentation strings, not paths.)
• Every edge in a call tree traces to real code read in this session or to a real task dependency. In ad-hoc mode, paths and relationships explicitly present in the supplied topic text also count as grounded — restating them is the job; adding ones the text does not support is not.
• Coverage lines come from the tasks' declared `satisfies` frontmatter (read with `$FLOWCTL cat <task-id>`) checked against the spec's R-IDs, not from re-narrated prose.
• No embellishment nodes "for clarity". When in doubt: **fewer nodes, more honest.**
• Nothing readable → say what was unreadable in one line, digest what is readable. A d