Visualize Plan

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:

--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

First, attempt auto-detection by running scripts/detect-plan-context.sh:

bash "$SKILL_DIR/scripts/detect-plan-context.sh"

This outputs branch name, issue number (if any), commit count, and file change summary.

If auto-detection finds a clear plan (branch with commits diverging from main, or issue number in args), proceed to Step 1.

If ambiguous, clarify with AskUserQuestion:

AskUserQuestion(
  questions=[{
    "question": "What should I visualize?",
    "header": "Source",
    "options": [
      {"label": "Current branch changes (Recommended)", "description": "Auto-detect from git diff against main"},
      {"label": "Describe the plan", "description": "I'll explain what I'm planning to change"},
      {"label": "GitHub issue", "description": "Pull plan from a specific issue number"},
      {"label": "Quick file diff only", "description": "Just show the change manifest, skip analysis"}
    ],
    "multiSelect": false
  }]
)

STEP 0.5: Probe Formats (silent — no question here)

Probe capabilities now so STEP 5 can offer only what will actually work. Do not ask anything at this step. Full procedure: Read("references/format-dispatch.md").

Use the established MCP-probe pattern — Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/mcp-detection.md") — not ad-hoc checks:

# infographic is available IFF the notebooklm studio tool resolves:
ToolSearch(query="select:mcp__notebooklm-mcp__studio_create")
# chart-encoding is available IFF the bundled /dataviz skill resolves
# (CC >= 2.1.198, disableBundledSkills off). It is a MARK-layer upgrade
# applied WITHIN a format, not a 4th format — see chart-encoding-standard.md.

Record what is available as AVAILABLE: ascii always (the floor); playground if the playground skill is installed (ships with ork); infographic if studio_create resolved above (server reachable + nlm login done). Orthogonally, if the /dataviz skill resolved, upgrade the chart marks in the non-ASCII formats via its form-heuristic + validated palette; if it did not resolve, charts stay ASCII-card — dataviz is never required.

FORMATS is then set without asking:

if   "--quick" in flags:        FORMATS = ["ascii"]              # and STEP 5 is skipped too
elif "--playground" in flags:   FORMATS = ["ascii", "playground"]
elif "--infographic" in flags:  FORMATS = ["ascii", "infographic"]
elif "--all" in flags:          FORMATS = AVAILABLE
else:                           FORMATS = ["ascii"]              # upgrade offered in STEP 5

ASCII floor rule: ASCII renders first/inline regardless — and because it never depends on the format choice, the choice is deferred to STEP 5 where it costs nothing. Never await the async NotebookLM job.

STEP 1: Gather Data

Run scripts/analyze-impact.sh for precise counts:

bash "$SKILL_DIR/scripts/analyze-impact.sh"

This produces: files by action (add/modify/delete), line counts, test files affected, and dependency changes.

--quick stops here — the impact script alone feeds the header, [1] Changes, and [5] Impact. No Explore agent, no before/after map, no memory write.

For architecture-level understanding and the default before/after section [0], spawn an Explore agent that maps the component graph at BOTH the base and the head:

Agent(
  subagent_type="Explore",
  prompt="Map component architecture of {affected_directories} at TWO points: (a) base = each file as returned by `git show origin/main:<path>` (NOT the working tree, to avoid conflating uncommitted edits), (b) head = current working tree. Return per point: components, dependencies, data flows; mark what is added [+], removed [-], or changed [~] between them. Use the glyph skill for diagrams.",
  model="haiku",
  max_turns=15
)

If the diff touches frontend (*.tsx/*.css/route files), also run a design-context-extract pass so the design surface is part of before/after. Patterns: Read("references/before-after-arch-patterns.md").

Build a compact plan brief (markdown) from this data — the single interchange every non-ASCII format consumes (see format-dispatch.md).

STEP 2: Render Tier 1 Header (Always)

Use assets/tier1-header.md template. Load Read("references/visualization-tiers.md") for field computation (risk level, confidence, reversibility).

PLAN: {plan_name} ({issue_ref})  |  {phase_count} phases  |  {file_count} files  |  +{added} -{removed} lines
Risk: {risk_level}  |  Confidence: {confidence}  |  Reversible until {last_safe_phase}
Branch: {branch} -> {base_branch}

[0] Before/After  [1] Changes  [2] Execution  [3] Risks  [4] Decisions  [5] Impact  [all]

STEP 3: Select Sections (no question — default to all)

Render all six sections. They are the content; asking which ones to render is asking the reviewer to choose before they have seen anything. The tier-1 header is already the progressive-disclosure layer, and a section with nothing to say is skipped with a one-line reason (not padded), so "all" never means "bloated".

SECTIONS = ["0","1","2","3","4","5"]      # default
if QUICK: SECTIONS = ["1","5"]            # --quick: change manifest + impact only

Section [0] Before/After leads whenever the Explore map shows structural changes, and is skipped with a one-line note otherwise. If the user asked for specific sections in their prompt ("just the risks"), honor that — but do not prompt for it.

STEP 4: Render Requested Sections

Render each requested section following rules/section-rendering.md conventions. Use the corresponding reference for ASCII patterns:

STEP 4b: Dispatch to Format(s)

Render the selected sections into the FORMATS chosen in STEP 0.5. ASCII always renders first/inline — the other formats consume the same plan brief. Full table + delegation patterns: Read("references/format-dispatch.md").

<branch-dir> = branch with / → -- (same path the PR Playground gate checks). The filename is always plan-viz.html — not index.html, not a topic name. One name is what makes slug lookup and the artifact gallery work at all.

Playground archetype: a plan visualization is usually a DASHBOARD — and as of 2026-08 that is a first-class archetype with a template, not a free pass. Copy shared/assets/playground-exemplars/plan-dashboard.template.html and swap the plan-state island; do not free-hand the CSS. It ships the §2 tokens, a sticky tier-1 header, <details> sections [0]–[5], a table twin per chart, the copy-prompt bar, and the reduced-motion gate. If the plan instead demonstrates a user-facing flow or a prioritization/decision, route to the user-story-player or decision-board archetype. Apply the §0 routing rule in Read("${CLAUDE_PLUGIN_ROOT}/shared/rules/playground-visual-standard.md") and run its §10 self-audit — including the DASHBOARD rows — before declaring done.

Backlog to dispatch? If the plan is a backlog the user must prioritize and route to execution, use the decision-router variant — each card routes to an ork strategy and emits a plan-only invocation: Read("references/decision-router.md").

Living plan (multi-wave)? If the plan executes over multiple sessions/waves, or completion is verifiable by commands, use the living-plan exemplar (living-plan.template.html): the playground embeds an lpp-state JSON block, every item carries a "done when" evidence check, and progress renders FROM state.

Update mode — detect by SLUG, never by path. The path is derived from the branch name, so a branch rename moves it and a path-keyed check silently forks the plan into a second file. Run the finder BEFORE authoring:

bash "$SKILL_DIR/scripts/find-living-plan.sh" "$SLUG"   # 0=update it · 1=author new · 2=already forked, STOP

On exit 0, MERGE into the file it printed (flip statuses, append changelog, move removed items to dropped) wherever it lives. On exit 2, do not write a third file — name both paths and ask which survives. Full contract: Read("references/format-dispatch.md") §Living-plan update mode. Gated by tests/orphans/test-duplicate-living-plans.sh.