fwd-explain

name

fwd:explain

description

Break down anything heavy — a plan, code file, diff, doc, stack trace, PR, URL, or concept — into a layered walkthrough. Builds a mental model first (problem framed + best-fit form: diagram, analogy, before/after, or causal narrative — plus structure map), then one chunk at a time on demand. Use when the input is too long to skim, when you've come back to something and lost the thread, or when ramping up on unfamiliar material.

Explain

Take anything heavy and build a mental model on demand: a one-screen frame (problem + mental model + map) first, then one chunk at a time when the user asks. The mental-model form adapts to the content; mechanical chunking does not replace pedagogical scaffolding. The chunk shape changes per input type (phases for a plan, sections for a code file, files for a diff) — the layered structure stays the same.

Opposite of /fwd:plan and /fwd:write-doc — those create, this one explains.

Step 1 — Resolve the target

Never prompt for confirmation — just dive in. If you grabbed the wrong target the user will tell you.

Detect the input type from $ARGUMENTS. Order matters — first match wins:

$ARGUMENTS form	Detected as	Loader
empty	most recent explainable block in conversation	scan context (see below)
starts with http:// or https://	URL	WebFetch (or gh pr view <N> if it's a GitHub PR/issue URL)
pr <N>, #<N>, or numeric only	GitHub PR or issue	gh pr view <N> then gh issue view <N>
diff, HEAD~N, <branch>...<branch>, or starts with git	git diff	run the implied git diff …
contains *, ?, [, {	glob	Glob
contains / or starts with ., ~, /	literal path	Read
bare filename with extension	repo-wide search	find . -type f -name "<NAME>" -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.claude/*' -print0 | xargs -0 ls -t 2>/dev/null | head -1 (newest mtime wins)
multi-line text containing at .* (.*:\d+) style frames	stack trace	take inline
anything else (free-form phrase)	concept search in this codebase	Grep for keywords, read top 3 hits

If nothing resolves: Couldn't resolve <arg>. Pass a path, glob, "diff", URL, "pr <N>", or paste the content. and stop.

Empty $ARGUMENTS — find the freshest thing in conversation

Scan the conversation for the most recent explainable block. Definition: any of —

• An ExitPlanMode tool call's plan parameter
• A pasted markdown / code / log block in a user message, length > 30 lines
• A long assistant message containing structural markers (## , Phase \d+, code fences, etc.), length > 30 lines

Pick most-recent by message order. Tie-break inside one message: longest qualifying block wins. No type preference, no confirmation.

If nothing meets the bar: Nothing to explain in this conversation. Pass a target. and stop.

Step 2 — Classify and parse (silent)

Once content is loaded, classify it. The class picks the chunk model:

Class	Chunk noun	What to extract per chunk
Plan	Phase	name, one-sentence goal, file count, files (path + note), verification
Code	Section	top-level defs (function, class, export), one-line purpose, key deps
Diff	File	per file: what changed, why (best guess), risk surface
Doc	Section	h2/h3 outline; one-sentence summary per section
Stack	Frame	user-code frames (skip framework noise); root-cause guess
Concept	Reference	top files/symbols matching the phrase; one-line role per item
Other	Section	structural split (headers, blank lines); 5–8 chunks

Always extract, regardless of class:

• The Question — what problem does this solve, or what question does it answer? 1 sentence, plain language. Frame the problem, not the artifact. ("How do I run code outside React's render cycle without breaking it?" beats "What does useEffect do?")
• Mental Model — the bridge that lets a reader hold this in their head. Pick the form that lands hardest:
  • Concrete + structural (architecture, flow, request lifecycle) → ASCII diagram
  • Abstract concept (hook, principle, design pattern) → analogy ("Think of it as X")
  • Migration / diff / refactor → contrast (before → after)
  • Bug / stack trace → causal narrative (X → Y → crash)
  • Nothing fits → first principles (1–2 sentences capturing the essence)
• Not (optional) — what this is NOT, to sharpen boundaries. Only include when the line is naturally sharp (often: concepts, APIs). Skip if forced.

Do not write any of this to the user yet. Hold it for Step 3.

Step 3 — Render Layer 1 (Big Picture). Stop after.

Output five blocks, in order. Whole response under 40 lines.

A. The Question — 1 line. Frame the problem, not the artifact. Plain language, no jargon dump.

B. Mental Model — pick the form that lands hardest for this content. Free judgment, no rigid table — let the heuristics from Step 2 guide you:

• Diagram — for concrete, structural content (flow, layers, call graph). 8–15 lines max, ┌─┐│└─┘ → ↓ ─→, no decoration. Patterns that fit well: layer cascade, before/after, sequence, tree, box-and-arrow, timeline.
• Analogy — for abstract concepts. 2–4 lines, "Think of it as X" — bridge to a familiar domain.
• Before/after — for migrations / diffs / refactors. 2–4 lines, old shape → new shape.
• Causal narrative — for bugs / stack traces. 2–4 lines, X → Y → crash.
• First principles — for content that none of the above fit. 1–2 sentences capturing the essence.

If no form lands, write no model added — <reason> and move on. If the source already contains a useful diagram, re-use it instead of inventing one.

C. Not (optional) — 1–2 lines, only if the boundary is naturally sharp. Skip silently if forced — never invent contrast to fill the slot.

D. Map — one numbered line per chunk, prefixed with the noun:

1. Phase: <name>          (<N> files)
2. Phase: <name>          (<N> files)
...

(For diff: 1. File: <path> (+12 −3). For code: 1. Section: <name> (<N> defs). Same shape, different noun.)

E. Menu — verbatim:

Reply with:
  next        → walk through chunk 1
  <#>         → jump to that chunk
  more        → expanded structured detail for current chunk
  full        → verbatim text for current chunk
  done        → wrap up

Stop. Do not preview chunk 1.

Step 4 — Layer 2 (one chunk per follow-up)

When the user replies next, <#>, back, or a chunk name, render that chunk only:

## <Noun> <N> — <name>      [<N>/<total>]

Goal: <one sentence>

<mini-diagram if the chunk has structure; skip otherwise>

Top items (top 5; reply "more" for all):
  <action>: <thing> — <note>
  ...

<Verification | Notes | Key insight>: <one line per item, or "none">

next | back | <#> | more | full | done

Under 25 lines. If item count > 5, show 5 and note that more reveals the rest. The [<N>/<total>] footer lets you re-orient if context gets tight.

Step 5 — Layer 3 (on-demand)

• more → expanded structured detail for the current chunk, no truncation. (Plan: full file table. Code: full bodies. Diff: full hunks. Doc: full section text. Stack: full frame context.)
• full → verbatim quote of the current chunk from the original source, in a fenced block.
• back → re-render the previous chunk.
• done → 3-line wrap-up: chunks covered, chunks skipped, suggested next move.

Style rules

• Plain English. No filler ("Let's", "Now we will", "Great question"). Direct.
• No emoji.
• Bullets and one-liners over paragraphs.
• Mental Model is not always a diagram. Pick analogy, contrast, narrative, or first principles when those land harder. Diagrams are one of five forms, not the default.
• Contrast ("Not") is opt-in. Only include when the boundary is naturally sharp — never invent contrast.
• The Question frames the problem, not the artifact. "What does useEffect do?" is weak; "How do I run code outside React's render cycle without breaking it?" is the right shape.
• Never dump the original verbatim unless the user asks for full.
• If the source already contains a useful diagram, re-use it (don't reinvent good art); otherwise draw your own when a diagram is the right form.
• Match depth to context — if the user clearly knows the domain, skip the basics.