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.

Uses .claude/deep-dive.local.md when present (richer context); without it, Riko orients from the README and entry points. 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
  Tip: run /deep-dive first for richer context.
  

• 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 ' ' '-' | LC_ALL=C tr -cd 'a-z0-9-' | sed 's/--*/-/g; s/^-//; s/-$//' | cut -c1-40)
if ! echo "$slug" | grep -q '[a-z0-9]'; then
  # Topic has no ASCII a-z0-9 chars (e.g. CJK topics) — fall back to a deterministic hash slug.
  slug="topic-$(printf '%s' "$ARGUMENTS" | cksum | cut -d' ' -f1)"
fi

Reader language: READER_LANG is the BCP-47 tag of the language the topic ($ARGUMENTS) is written in (for example en or zh-TW), defaulting to en. Decide it once here and pass it to Phases 2–3.

Precondition Checks

Run these checks before dispatching any agents:

if [[ ! -f ".claude/deep-dive.local.md" ]]; then
  echo "Note: .claude/deep-dive.local.md not found. Continuing without it. For richer context run /deep-dive first."
fi

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