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. ```bash 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 ```python 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. ```python # 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 ```python # 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 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: ```python 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: ```python # 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**: ```python 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 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: ```python 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". ```python 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: | Section | Reference | Key Convention | |---------|-----------|----------------| | [0] Before/After Arch | (load `references/before-after-arch-patterns.md`) | Side-by-side base vs head; mark `[+]`/`[~]`/`[-]`; skip if nothing structural changed | | [1] Change Manifest | (load `references/change-manifest-patterns.md`) | `[A]`/`[M]`/`[D]` + `+N -N` per file | | [2] Execution Swimlane | (load `references/execution-swimlane-patterns.md`) | `===` active, `---` blocked, `\|` deps | | [3] Risk Dashboard | (load `references/risk-dashboard-patterns.md`) | Reversibility timeline + 3 pre-mortems | | [4] Decision Log | (load `references/decision-log-patterns.md`) | ADR-lite: Context/Decision/Alternatives/Tradeoff | | [5] Impact Summary | (load `assets/impact-dashboard.md`) | Table: Added/Modified/Deleted/NET + tests/API/deps | --- ## 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")`. | Format | Action | |--------|--------| | ASCII | Native render (above) — always, the floor | | Playground | Classify the archetype (below), then hand the plan brief to the `playground` skill → write `docs/<branch-dir>/plan-viz.html`, then serve it with `page-serve docs/<branch-dir>/plan-viz.html` and put the printed `url=` in the reply's Open section (never a bare path or a hand-started http.server) | | Infographic | Run the `notebooklm` `studio_create(artifact_type=infographic\|slides)` flow — **fire-and-notify**, poll `studio_status`, never await | | All | ASCII inline now + the rest linked as they finish | | Charts (marks *within* Playground / Infographic) | For sections with quantitative marks — **[3] Risk, [5] Impact, [6] Blast Radius** — pick the form via `/dataviz` (`choosing-a-form`) and the palette via its 6-check formula, then run `validate_palette.js`. On validator FAIL **or** `/dataviz` absent, fall back to the ASCII-card layout. Chrome stays ork tokens (§2 of `playground-visual-standard.md`); only the data marks come from the validated palette. See `${CLAUDE_PLUGIN_ROOT}/shared/rules/chart-encoding-standard.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