flow-next-visual

# 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`:

```bash
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 digest that quietly invents the missing half is worse than a short one.

## Degradation

- No tasks yet → pre-plan spec digest.
- No spec (or the id resolves to nothing) → diff digest if a range applies, else ad-hoc restate.
- No flowctl, no flow install, or not a git repo → ad-hoc restate, with a one-line notice of what was unavailable. The vocabulary needs neither.

## Shape vocabulary

Pick the **smallest** view that makes the key point clear. Place each visual **next to the short text it supports** — the visual supplements a o