/visualize-plan

name: visualize-plan
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Renders planned changes as before/after architecture, risk heat maps, execution order and dependency graphs in ASCII, HTML or NotebookLM. Use when reviewing a plan. Not for an inline chart (use glyph)."
argument-hint: "[plan-or-issue]"
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
agent: workflow-architect
model: sonnet
user-invocable: true
allowed-tools: "Read Grep Glob Agent TaskCreate TaskUpdate AskUserQuestion Bash Write mcp__memory__search_nodes mcp__memory__create_entities ToolSearch mcp__notebooklm-mcp__studio_create"
skills: [glyph, explore, architecture-decision-record, memory, remember, page-serve]
metadata:
  category: document-asset-creation
  mcp-server: memory
  version: "2.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "visualization, planning, before-after, architecture, diff, risk, impact, migration, playground, infographic, multi-format"
triggers:
  keywords: [visualize, "visualize plan", "visualize the plan", "visualize the", "show diagram", "before and after", "execution order", "risk and impact", swimlane, "what files will change"]
  examples:
    - "visualize the plan for the billing module redesign"
    - "show me a before and after diagram for this migration"
    - "whats the risk and impact of the changes"
  anti-triggers: [implement, brainstorm, explore, assess, fix]

Plan Visualization

Render planned changes as structured ASCII visualizations with risk analysis, execution order, and impact metrics. Every section answers a specific reviewer question.

**Core principle:** Encode judgment into visualization, not decoration.

visualize-plan                          # Auto-detect from current branch
visualize-plan billing module redesign  # Describe the plan
visualize-plan #234                     # Pull from GitHub issue
visualize-plan --quick                  # Header + changes + impact, zero questions
visualize-plan --playground             # Skip straight to the HTML dashboard
visualize-plan --infographic            # Skip straight to NotebookLM

Argument Resolution

PLAN_INPUT = "$ARGUMENTS"    # Full argument string
PLAN_TOKEN = "$ARGUMENTS[0]" # First token — could be issue "#234" or plan description
# If starts with "#", treat as GitHub issue number. Otherwise, plan description.
# $ARGUMENTS (full string) for multi-word descriptions (CC 2.1.59 indexed access)

# Flags are stripped from PLAN_INPUT before it is used as a description:
#   --quick        → QUICK=true: tier-1 header + [1] Changes + [5] Impact, no Explore
#                    agent, no questions at all, no memory write. The 15-second answer.
#   --playground   → FORMATS=[ascii, playground]      (no format question)
#   --infographic  → FORMATS=[ascii, infographic]     (no format question)
#   --all          → FORMATS=[ascii, + everything the probe found]

Question budget: ZERO before the first render

This skill used to ask three blocking questions (source, then format, then sections) before a single character rendered, plus a fourth after. That is why fast paths leaked to `glyph` and to hand-written HTML.

The format answer is **not needed** to render ASCII — the ASCII floor rule renders it first regardless of what the user picks. So asking up front buys nothing and costs a round-trip. The rule now:

| Decision | When | How | |---|---|---| | Source | before | Auto-detect. Ask **only** if detection is genuinely ambiguous (STEP 0). | | Sections | never | Default to **all**. The tier-1 header is the progressive-disclosure layer. | | Format | **after** ASCII | One post-render question (STEP 5), merged with drill-deeper. |

`--quick` skips even that one.

Budget: at most 1 Explore agent and one post-render question (STEP 5); stop and report at the finish line or the first cap, whichever comes first.

---

CRITICAL: Task Tracking

**`--quick` skips this whole block.** A 15-second render does not need a dependency graph; the task overhead would cost more than the work.

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Visualize plan: {PLAN_INPUT}", description="Plan visualization with ASCII rendering", activeForm="Analyzing plan context")

# 2. Create subtasks for each phase
TaskCreate(subject="Detect or clarify plan context", activeForm="Detecting plan context")          # id=2
TaskCreate(subject="Gather data and explore architecture", activeForm="Gathering plan data")       # id=3
TaskCreate(subject="Render tier 1 header", activeForm="Rendering header")                          # id=4
TaskCreate(subject="Render sections + dispatch to chosen format(s)", activeForm="Rendering sections") # id=5
TaskCreate(subject="Offer actions and store in memory", activeForm="Finalizing visualization")     # id=6

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Data gathering needs context first
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Header needs gathered data
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Sections need header rendered
TaskUpdate(taskId="6", addBlockedBy=["5"])  # Actions need sections done

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

STEP -1: Check Memory for Prior Plans

# Search for related prior visualizations
mcp__memory__search_nodes(query="plan visualization {PLAN_INPUT}")
# If found, offer to compare with previous plan

STEP 0: Detect or Clarify Plan Context

**Plan context, already detected.** Claude Code ran `scripts/detect-plan-context.sh` when it opened this skill (a body step can be skipped, #4683). Its output, the branch name, issue number (if any), commit count and file change summary, is below (first 60 lines; the file list can run to thousands of