/visualize-plan

description: "Renders planned changes — architecture and before/after comparisons, risk heat maps, execution order, dependency graphs, impact metrics — in your chosen output format (ASCII + emojis, an interactive HTML playground, or a NotebookLM infographic). Stores visualizations in memory for cross-session reference. Use when reviewing implementation plans, comparing approaches, assessing risk, or analyzing change propagation."
argument-hint: "[plan-or-issue]"
model: sonnet
context: fork
agent: workflow-architect
user-invocable: true
name: visualize-plan
background: false
allowed-tools: [Read, Grep, Glob, Agent, TaskCreate, TaskUpdate, AskUserQuestion, Bash, Write, mcp__memory__search_nodes, mcp__memory__create_entities, ToolSearch]

Auto-generated from skills/visualize-plan/SKILL.md

Source: https://github.com/yonatangross/orchestkit

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.

/ork:visualize-plan                          # Auto-detect from current branch
/ork:visualize-plan billing module redesign  # Describe the plan
/ork:visualize-plan #234                     # Pull from GitHub issue
/ork:visualize-plan --quick                  # Header + changes + impact, zero questions
/ork:visualize-plan --playground             # Skip straight to the HTML dashboard
/ork: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.

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