explain

Explain Command

Generate an interactive HTML explainer for a codebase topic. Riko gathers the relevant code scope, Senku designs a 3–5 screen teaching arc, Speedwagon authors the module brief and HTML fragment, and the assembler concatenates everything into explain-out/index.html — a file you can open directly in a browser.

Requires .claude/deep-dive.local.md (run /deep-dive first). The graphify knowledge graph (graphify-out/graph.json) is used if present; absent it degrades gracefully.

Argument Parsing

$ARGUMENTS is the raw argument string passed to this command.

• If $ARGUMENTS is empty → print usage error and stop:

  Usage: /agent-flow:explain <topic>
  Example: /agent-flow:explain how does orchestration work
  Run /deep-dive first if you haven't already.
  

• If $ARGUMENTS starts with --revise → revise mode: extract the slug from the argument (e.g. --revise orchestration-pipeline) and skip Phase 1–2 if the brief exists.
• Otherwise → normal mode: $ARGUMENTS is the full topic string.

Slug derivation (compute once, use throughout all phases):

slug=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | cut -c1-40)

Precondition Checks

Run these checks before dispatching any agents:

if [[ ! -f ".claude/deep-dive.local.md" ]]; then
  echo "Error: .claude/deep-dive.local.md not found."
  echo "Run /deep-dive first to build the codebase context."
  exit 1
fi

if [[ ! -f "graphify-out/graph.json" ]]; then
  echo "Note: graphify-out/graph.json not found. Continuing in degraded mode (no graph context)."
fi

Phase 1 — Scope (Riko)

Dispatch Riko with this prompt template, substituting $ARGUMENTS for TOPIC and the actual content of .claude/deep-dive.local.md for DEEP_DIVE_CONTEXT:

TOPIC: $ARGUMENTS

You are gathering code scope for a topic explainer. Your output will be consumed by
Senku (curriculum design) and Speedwagon (HTML authoring) — keep it structured.

Steps:
1. Read .claude/deep-dive.local.md for architecture context.
2. If graphify-out/graph.json exists, query for nodes related to the topic.
3. Identify 3–8 file:line refs directly relevant to the topic (concrete functions,
   types, or config values — not just filenames).
4. Identify 2–4 graph node names (or write "graph: unavailable" if graph absent).
5. Extract 3–6 key terminology terms specific to this topic.

Return structured markdown in exactly this format:

## Scope Bundle: $ARGUMENTS

### File References
- <file>:<start>-<end>  — <one-line description>
...

### Graph Nodes
- <node-name>
...  (or: graph: unavailable)

### Key Terminology
- <term>: <definition>
...