# Visual

Source: https://flow-next.dev/skills/visual/

Restate a spec, task, diff, or the current topic as a compact markdown digest - the visual view of any spec, plan, or diff.

`/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.

```bash
/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.

For a visual view of a spec, a plan, or a diff, run `/flow-next:visual`; it replaces the HTML render lenses, which 7.0 removed. When you want an HTML page, ask the agent for one. The digest needs zero machinery and 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.
>
> ```text
> 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/refine
>   ├─ .3 make-pr sketch license        → mermaid-rules §8
>   └─ .4 platform + listing surfaces   → sync-codex, counts, CHANGELOG
>      └─ .5 conduct + tests + dogfood  → checklist, prose-contract pins
> ```
>
> ```diff
> 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 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.

## Everything it shows is grounded

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:plan`](https://flow-next.dev/skills/plan/) and [`/flow-next:refine`](https://flow-next.dev/skills/refine/) each offer the digest at their read-back moment - one suggested-next-step line, an option you pick, never auto-run.