--- title: "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." canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/visualize-plan" --- # Visualize Plan 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. Command medium ```bash title="Invoke" /ork:visualize-plan ``` > **Visualize Plan** 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. # 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 /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 ```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. --- ## 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("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/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:` (NOT the working tree — avoids 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" ) ``` 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("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/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("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/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 `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/rules/section-rendering.md` conventions. Use the corresponding reference for ASCII patterns: | Section | Reference | Key Convention | |---------|-----------|----------------| | [0] Before/After Arch | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/before-after-arch-patterns.md`) | Side-by-side base vs head; mark `[+]`/`[~]`/`[-]`; skip if nothing structural changed | | [1] Change Manifest | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/change-manifest-patterns.md`) | `[A]`/`[M]`/`[D]` + `+N -N` per file | | [2] Execution Swimlane | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/execution-swimlane-patterns.md`) | `===` active, `---` blocked, `\|` deps | | [3] Risk Dashboard | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/risk-dashboard-patterns.md`) | Reversibility timeline + 3 pre-mortems | | [4] Decision Log | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/decision-log-patterns.md`) | ADR-lite: Context/Decision/Alternatives/Tradeoff | | [5] Impact Summary | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/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("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/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`, link it | | 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, `
` > 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("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/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 > 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("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/format-dispatch.md")` > §Living-plan update mode. Gated by `tests/orphans/test-duplicate-living-plans.sh`. --- ## STEP 5: Offer Actions — the ONE question This is the only blocking question in a default run, and it carries the format choice that used to block at STEP 0.5. **Skip it entirely when `--quick`, or when the format was set by flag and there is nothing left to offer.** Build the option list from what the STEP 0.5 probe actually found — never offer a path that will fail. ```python options = [] if "playground" in AVAILABLE and "playground" not in FORMATS: options.append({"label": "Interactive dashboard (Recommended)", "description": "Single-file HTML at docs//plan-viz.html, from plan-dashboard.template.html. Also satisfies the PR Playground gate. Multi-wave plans become LIVING plans, updated in place."}) if "infographic" in AVAILABLE and "infographic" not in FORMATS: options.append({"label": "NotebookLM infographic", "description": "Stakeholder-ready infographic/slides. Async — fired and notified, never blocks."}) options.append({"label": "Drill deeper", "description": "Blast radius, cross-layer consistency, or migration checklist"}) options.append({"label": "Generate GitHub issues", "description": "One issue per execution phase, with labels, milestone, and blocked-by links"}) # AskUserQuestion caps at 4 options. "Done" must ALWAYS survive that cap — an # actions menu with no exit is a trap — so reserve its slot instead of appending. DONE = {"label": "Done", "description": "Plan visualization complete"} AskUserQuestion(questions=[{"question": "What next?", "header": "Actions", "options": options[:3] + [DONE], "multiSelect": False}]) ``` Anything squeezed out by the cap stays reachable by asking — the menu is a shortcut, not the whole surface. `Write to designs/\{branch\}.md` (template: `assets/plan-report.md`) is one of these. Upgrading reuses the plan brief built in STEP 1 — **no recomputation** (see `references/format-dispatch.md`). If nothing richer is available, the question drops to drill-deeper / issues / done. **Write to file:** Save full report to `designs/\{branch-name\}.md` using `assets/plan-report.md` template. **Generate issues:** For each execution phase, create a GitHub issue with title `[\{component\}] \{phase_description\}`, labels (component + `risk:\{level\}`), milestone, body from plan sections, and blocked-by references. **Store in memory:** Save plan summary to knowledge graph for future comparison: ```python mcp__memory__create_entities(entities=[{ "name": "Plan: {plan_name}", "entityType": "plan-visualization", "observations": [ "Branch: {branch}", "Risk: {risk_level}, Confidence: {confidence}", "Phases: {phase_count}, Files: {file_count}", "Key decisions: {decision_summary}" ] }]) ``` --- ## Deep Dives (Tier 3, on request) Available when user selects "Drill deeper". Load `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/deep-dives.md")` for cross-layer and migration patterns. | Section | What It Shows | Reference | |---------|--------------|-----------| | [6] Blast Radius | Concentric rings of impact (direct -> transitive -> tests) | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/blast-radius-patterns.md`) | | [7] Cross-Layer Consistency | Frontend/backend endpoint alignment with gap detection | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/deep-dives.md`) | | [8] Migration Checklist | Ordered runbook with sequential/parallel blocks and time estimates | (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/deep-dives.md`) | --- ## Key Principles | Principle | Application | |-----------|-------------| | **Progressive disclosure** | Tier 1 header always, sections on request | | **Judgment over decoration** | Every section answers a reviewer question | | **Precise over estimated** | Use scripts for file/line counts | | **Honest uncertainty** | Confidence levels, pre-mortems, tradeoff costs | | **Actionable output** | Write to file, generate issues, drill deeper | | **Anti-slop** | No generic transitions, no fake precision, no unused sections | ## Rules Quick Reference | Rule | Impact | What It Covers | |------|--------|----------------| | section-rendering (load `$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/rules/section-rendering.md`) | HIGH | Rendering conventions for all 6 core sections ([0]–[5]) | | ASCII diagrams | MEDIUM | Via `glyph` skill (box-drawing, file trees, workflows) | ## References Load on demand with `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/<file>")`: | File | Content | |------|---------| | `visualization-tiers.md` | Progressive disclosure tiers and header field computation | | `change-manifest-patterns.md` | Change manifest ASCII patterns | | `execution-swimlane-patterns.md` | Execution swimlane ASCII patterns | | `risk-dashboard-patterns.md` | Risk dashboard ASCII patterns | | `decision-log-patterns.md` | Decision log ASCII patterns | | `blast-radius-patterns.md` | Blast radius ASCII patterns | | `deep-dives.md` | Cross-layer consistency and migration checklist | | `format-dispatch.md` | Output-format capability probe, ASCII-floor rule, delegation to playground/notebooklm | | `before-after-arch-patterns.md` | Section [0] before/after architecture per output format | ## Examples (read one before your first run) Complete worked runs — real input, real ASCII output, real emitted artifact. The ASCII patterns in them match `references/*-patterns.md` exactly, so they are safe to imitate directly. | File | Shows | |------|-------| | `examples/01-dashboard-run.md` | The default path end to end: detect → gather → header → all six sections → the one question → the emitted HTML. Same scenario as the sample state in `plan-dashboard.template.html`. | | `examples/02-living-plan-update.md` | Update mode on a **renamed branch**: slug-keyed detection, the JSON merge, the evidence gate, and the exit-2 fork case. | | `examples/03-quick-run.md` | `--quick`: what is skipped, what the output looks like, and what it must never fabricate. | ## Assets Load on demand with `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/assets/<file>")`: | File | Content | |------|---------| | `plan-report.md` | Full mustache-style report template | | `impact-dashboard.md` | Impact table template | | `tier1-header.md` | 5-line summary template | ## Quality Bar Done means all of these hold: - The Tier 1 header always renders with every field populated — risk, confidence, reversibility, branch, and file/line counts. - File and line counts come from `scripts/analyze-impact.sh`, not estimated or guessed. - Every rendered section answers its reviewer question; a section with no content is skipped with a one-line reason, never padded. - **Section [3] names the point of no return by phase id** (`--- POINT OF NO RETURN (after P3) ---`), not by implication, and each pre-mortem states a **mechanism** — trigger, sequence, resulting bad state — not a category. "Migration risk" is a heading; "P2 ships while an in-flight retry queue still points at the inline charge path, so the same invoice is charged twice" is a pre-mortem. This is the section's measured failure mode, not a style preference: `rules/section-rendering.md` §[3] carries the falsifiable test for both. - Section [0] Before/After maps base (`git show origin/main:<path>`) against head (working tree), marking each node `[+]`/`[~]`/`[-]`, and is skipped with a note when nothing structural changed. - ASCII renders first/inline regardless of chosen format; any async format (infographic) is fired-and-notified, never awaited. - The plan summary is stored to the memory knowledge graph for cross-session comparison (skipped under `--quick`). - **Zero blocking questions before the first render.** Source is auto-detected (asked only when genuinely ambiguous), sections default to all, and format is chosen after the ASCII floor is already on screen — at most one question per run, none under `--quick`. - A playground output started from `plan-dashboard.template.html` (or the living-plan / player / board exemplar the §0 routing rule selected) — never hand-rolled CSS — and passed the §10 self-audit including the DASHBOARD rows. - A living plan was located by **slug** via `scripts/find-living-plan.sh` before authoring, so an existing plan is updated in place rather than forked into a second file. ## Related Skills - `ork:implement` - Execute planned changes - `ork:explore` - Understand current architecture - `ork:assess` - Evaluate complexity and risks - `ork:memory` - Search prior plan visualizations - `ork:remember` - Store plan decisions for future reference --- ## Rules (1) ### Section Rendering Conventions — HIGH # Section Rendering Conventions Each visualize-plan section follows strict rendering rules to ensure consistency and reviewer utility. ## General Rules 1. **Every section answers ONE reviewer question** — if it doesn't answer a question, cut it 2. **Use scripts for precision** — run `analyze-impact.sh` for file/line counts, never estimate 3. **Annotations carry judgment** — `!!` for risk, `**` for new, `blocks` for dependencies 4. **Summary lines are mandatory** — every section ends with a one-line summary **Incorrect:** ``` Files Changed: - auth.py (modified) - utils.py (new) ``` **Correct:** ``` [M] src/auth.py +42 -8 !! security-critical [A] src/utils.py +65 -0 **new** Summary: +107 -8 | 1 new | 1 modified | 0 deleted ``` ## Section [1]: Change Manifest - Use `[A]`/`[M]`/`[D]` prefix symbols (Terraform convention) - Show `+N -N` line counts per file - Flag high-risk files with `!!` and annotation - Mark new files with `**` - Always end with a summary line: `Summary: +N -N | X new | Y modified | Z deleted` ## Section [2]: Execution Swimlane - `===` for active work, `---` for blocked/waiting - Vertical `|` for dependencies with `blocks` annotations - Identify and label the critical path - Show parallel opportunities explicitly ## Section [3]: Risk Dashboard - Part A: Reversibility timeline with `[====]` bars - Always identify the point of no return with `--- POINT OF NO RETURN ---` - Part B: Exactly 3 pre-mortem scenarios (most likely, most severe, most subtle) - Each scenario needs a concrete mitigation, not generic advice ### Name the phase, do not imply it Measured failure, not hypothetical: a 2026-08-04 eval graded real output as *"Four execution phases shown but no explicit statement of which phase is the irreversible point"*. The rule above was already present and still not followed, so it now carries a test. The point of no return is a *phase identifier*, not a mood. If a reader cannot answer "after which phase can I no longer undo this?" by pointing at one token, the section failed. ``` ❌ WRONG "later phases are harder to reverse" ❌ WRONG "merging to main makes this permanent" ← implied, unnamed ✅ RIGHT --- POINT OF NO RETURN (after P3) --- P4 drops the legacy column; data is unrecoverable from that point. ``` Test: does the literal phase id appear on the same line as the marker? For the second measured failure — pre-mortems that name a *category* instead of a *mechanism* — see the "state a MECHANISM, not a category" rule in `references/risk-dashboard-patterns.md`, which is where the pre-mortem patterns live. ## Section [4]: Decision Log - ADR-lite format: Context, Decision, Alternatives, Tradeoff - Only document non-obvious decisions (skip "we need a database table") - Always show at least one rejected alternative - Tradeoffs must be honest — show the cost, not just the benefit ## Section [5]: Impact Summary - Table format with Categories (Added, Modified, Deleted, NET) - Include: Tests coverage delta, API surface changes, dependency changes - Use `assets/impact-dashboard.md` template --- ## References (10) ### Before/After Architecture Patterns # Before/After Architecture — Section [0] The default lead section. Answers the reviewer's first question: **"what does this change about the shape of the system?"** Computed once in STEP 1 from the Explore agent's component map (pre-diff `git stash`/base vs post-diff working tree), reused by every format. ## Data source ```python Agent(subagent_type="Explore", model="haiku", prompt=""" Map the component architecture of {affected_dirs} at TWO points: (a) base = origin/main (pre-plan) (b) head = working tree (post-plan) Return for each: components, their dependencies, and what MOVED/ADDED/REMOVED between (a) and (b). Mark new components [+], removed [-], changed [~]. """) ``` If the plan touches **frontend** (detected via changed `*.tsx`/`*.css`/route files), also fire a `design-context-extract` pass so the design surface (tokens, key screens) is part of before/after — not just the module graph. Backend-only plans get architecture only. ## ASCII format (the floor) Side-by-side, base on the left, head on the right, deltas marked: ``` BEFORE (origin/main) AFTER (this plan) ───────────────────── ───────────────────── ┌──────────┐ ┌──────────┐ │ API │ │ API │ └────┬─────┘ └────┬─────┘ │ │ ┌────▼─────┐ ┌────▼─────┐ ┌───────────┐ │ Auth │ │ Auth │──▶│ OAuth svc │ [+] └────┬─────┘ └────┬─────┘ └───────────┘ │ │ ┌────▼─────┐ ┌────▼─────┐ │ Postgres │ │ Postgres │ └──────────┘ └──────────┘ [+] new [~] changed [-] removed ``` Keep both columns to the same component set so the eye diffs by position. Annotate only what changed; don't redraw-for-decoration. ## Playground (HTML) format Render the two graphs as a side-by-side Mermaid `flowchart`, with changed nodes class-styled (`classDef added`, `removed`, `changed`) and a toggle to overlay only the delta. The `playground` skill wraps it in the standard single-file explorer. Write to `docs/<branch-dir>/plan-viz.html`. ## NotebookLM infographic format Feed the before/after brief (module lists + deltas + the one-line "why") as a source doc, then `studio_create(artifact_type=infographic)`. The infographic is for **stakeholders** — lead with the delta narrative ("3 services become 4; auth gains an OAuth dependency"), not the full graph. ## Anti-slop - No before/after when nothing structural changed (pure refactor within a module) — say so in one line and skip the section. - Don't invent components to fill symmetry. If the plan only touches one module, show that module's internal before/after, not a fake system map. ### Blast Radius Patterns # Blast Radius Patterns Visualize the transitive impact of planned changes. ## Concentric Rings The changed file at center, expanding rings for each degree of dependency: ``` Ring 3: Tests (8 files) +-------------------------------+ | Ring 2: Transitive (5) | | +------------------------+ | | | Ring 1: Direct (3) | | | | +--------------+ | | | | | CHANGED FILE | | | | | +--------------+ | | | +------------------------+ | +-------------------------------+ Ring 1 (direct): auth.py, routes.py, middleware.py Ring 2 (transitive): app.py, config.py, utils.py, cli.py, server.py Ring 3 (tests): test_auth.py, test_routes.py, ... (+6 more) ``` ## Multi-File Blast Radius When multiple files change, show overlapping impact: ``` BLAST RADIUS: 3 changed files memory-writer.ts ─── Ring 1: 5 files ─── Ring 2: 12 files ─── Ring 3: 8 tests | | memory-health.ts ─── Ring 1: 3 files ────+ | | | | queue-processor.ts ── Ring 1: 2 files ──+─+───+ Overlap: 4 files appear in multiple blast radii Unique impact: 18 files total (not 25 — overlap deduplicated) ``` ## Fan-In / Fan-Out Analysis ``` Fan-In (what depends on changed files) Fan-Out (what changed files depend on) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ memory-writer.ts [========] 8 graph-client [======] 6 memory-health.ts [====] 4 cc-native-writer [====] 4 queue-processor.ts [==] 2 logger [==] 2 decision-history.ts [===] 3 config [=] 1 High fan-in = higher risk (more things break if this file breaks) High fan-out = higher complexity (more things to understand) ``` ## Dependency Tree (Detailed) ``` BLAST RADIUS: memory-writer.ts memory-writer.ts (CHANGED) ├── stop/auto-remember-continuity.ts (direct dependent) │ ├── stop/unified-dispatcher.ts (transitive) │ │ └── hooks.json (config entry) │ └── stop/session-patterns.ts (transitive) ├── stop/session-profile-aggregator.ts (direct dependent) ├── subagent-stop/unified-dispatcher.ts (direct dependent) ├── skill/decision-processor.ts (direct dependent) │ └── skill/unified-dispatcher.ts (transitive) └── lifecycle/pre-compact-saver.ts (direct dependent) Direct: 5 files | Transitive: 3 files | Total: 8 files ``` ## Impact by Layer For full-stack changes, show blast radius per layer: ``` BLAST RADIUS BY LAYER API Layer: Changed: routes.py, schemas.py Impact: middleware.py, auth.py (2 dependents) Tests: test_routes.py, test_auth.py (2 test files) Service Layer: Changed: billing.py (new) Impact: None (new file, no dependents yet) Tests: test_billing.py (new, paired) Model Layer: Changed: invoice.py (new) Impact: billing.py depends on it (1 dependent) Tests: test_models.py needs update (1 test file) Frontend: Changed: InvoiceList.tsx, InvoiceDetail.tsx (new) Impact: App.tsx (routing), Sidebar.tsx (navigation) Tests: InvoiceList.test.tsx (new, paired) Cross-Layer Dependencies: Frontend -> API: 2 new fetch calls (POST /invoices, GET /invoices) API -> Model: 1 new import (InvoiceModel) ``` ## Compact Blast Radius (small changes) ``` BLAST RADIUS: routes.py -> 3 direct, 5 transitive, 4 tests = 12 files ``` ### Change Manifest Patterns # Change Manifest Patterns Terraform-style annotated file trees for visualizing planned changes. ## Symbol Convention Borrowed from Terraform plan output for universal recognition: ``` [A] Add — New file being created [M] Modify — Existing file being changed [D] Delete — File being removed [R] Rename — File being moved/renamed [S] Simplify — File being reduced (lines removed, logic simplified) ``` ## Annotation Convention ``` !! Risk flag — High-traffic path, complex logic, or fragile code ** New file — Freshly created, no existing behavior to break ~~ Deprecated — Being replaced by another file -> Moves to — Content relocating to a different path ``` ## Basic Change Tree ``` src/ ├── api/ │ ├── routes.py [M] +45 -12 │ └── schemas.py [M] +20 -5 ├── services/ │ └── billing.py [A] +180 ** new file ├── models/ │ └── invoice.py [A] +95 ** new file └── tests/ └── test_billing.py [A] +120 ** new file Legend: [A]dd [M]odify [D]elete !! Risk ** New Summary: +460 -17 | 3 new | 2 modified | 0 deleted ``` ## Annotated Change Tree (with risk flags) ``` src/ ├── hooks/ │ ├── lifecycle/ │ │ ├── mem0-context-retrieval.ts [D] -245 ~~ replaced by graph │ │ ├── mem0-analytics-tracker.ts [D] -180 ~~ no replacement needed │ │ └── pre-compact-saver.ts [S] -40 remove mem0 fallback │ ├── stop/ │ │ ├── mem0-queue-sync.ts [D] -320 ~~ queue system removed │ │ └── auto-remember-continuity.ts [S] -25 !! touches session persistence │ ├── lib/ │ │ ├── memory-writer.ts [S] -350 !! core write path │ │ ├── queue-processor.ts [D] -280 ~~ queue system removed │ │ └── memory-health.ts [S] -60 remove mem0 health checks │ └── setup/ │ ├── mem0-backup-setup.ts [D] -150 │ ├── mem0-cleanup.ts [D] -120 │ └── mem0-analytics-dashboard.ts [D] -200 ├── skills/ │ ├── mem0-memory/ [D] -4500 ~~ entire skill removed │ ├── memory-fabric/SKILL.md [S] -80 remove mem0 paths │ └── remember/SKILL.md [S] -45 remove --mem0 flag └── tests/ └── mem0/ [D] -3200 ~~ 20 test files removed Legend: [A]dd [M]odify [D]elete [S]implify !! Risk ** New ~~ Deprecated Summary: +0 -9,795 | 0 new | 4 simplified | 30 deleted ``` ## Grouped by Action For large changesets, group by action type: ``` DELETIONS (30 files, -9,195 lines): src/skills/mem0-memory/ [D] 42 files -4,500 lines tests/mem0/ [D] 20 files -3,200 lines src/hooks/src/lifecycle/mem0-* [D] 2 files -425 lines src/hooks/src/stop/mem0-* [D] 2 files -520 lines src/hooks/src/setup/mem0-* [D] 3 files -470 lines bin/mem0-*.py [D] 2 files -80 lines SIMPLIFICATIONS (4 files, -600 lines): src/hooks/src/lib/memory-writer.ts [S] -350 lines !! core write path src/skills/memory-fabric/SKILL.md [S] -80 lines src/skills/remember/SKILL.md [S] -45 lines src/hooks/src/lib/memory-health.ts [S] -60 lines src/hooks/src/stop/auto-remember.ts [S] -25 lines !! session persistence NO CHANGES (185 files): All other skills, agents, hooks unchanged ``` ## Compact Format (for small changes) ``` CHANGES: 3 files (+85 -12) [M] src/api/routes.py +45 -12 !! hot path [A] src/api/schemas.py +20 [A] tests/test_routes.py +20 ``` ### Decision Log Patterns # Decision Log Patterns ADR-lite format for documenting non-obvious choices in a plan. ## When to Document a Decision Document when ANY of these apply: - Multiple valid approaches exist and one was chosen over others - The choice has a meaningful tradeoff (something is gained AND lost) - Future developers would ask "why was it done this way?" - The decision constrains future options Do NOT document: - Obvious choices ("we need a table for invoices") - Implementation details ("use for loop vs map") - Forced choices (only one option exists) ## Standard Decision Entry ``` #1: Use graph-only memory instead of dual-write Context: Current system writes to 3 tiers (graph + .jsonl + mem0 cloud). Only graph tier is used by 98% of queries. Decision: Remove .jsonl and mem0 cloud tiers. Write only to graph + CC native. Alternatives: [a] Keep mem0 as optional -> still 14K lines of code to maintain [b] Abstract behind interface -> over-engineering for 2% usage Tradeoff: + 14K lines removed, 39 Python scripts gone, zero external deps - Lose cloud semantic search (affects cross-session pattern matching) Confidence: HIGH (usage data confirms <2% mem0 queries) ``` ## Compact Decision Entry For plans with many small decisions: ``` DECISIONS #1 Graph-only memory (not dual-write) + 14K lines removed - lose cloud search | Confidence: HIGH #2 Delete queue processor (not simplify) + no background jobs - no retry on write failure | Confidence: HIGH #3 Keep decision-flow-tracker (not delete) + behavioral intelligence preserved - 200 lines to maintain | Confidence: MEDIUM ``` ## Decision with Alternatives Matrix When comparing 3+ options: ``` DECISION: Memory write strategy +=================+===========+==========+========+==========+ | Option | Lines | Ext Deps | Speed | Coverage | +=================+===========+==========+========+==========+ | Graph-only [X] | -14,100 | 0 | Fast | 98% | | Dual-write | -0 | 1 (mem0) | Medium | 100% | | Abstract layer | +500 | 0 | Medium | 100% | +-----------------+-----------+----------+--------+----------+ [X] = Selected option Rationale: 14K line reduction outweighs 2% coverage gap. Cloud search can be re-added later if needed (additive change). ``` ## Decision Chain (dependent decisions) When one decision forces subsequent decisions: ``` DECISION CHAIN #1 Remove mem0 cloud tier | +-> #2 Delete 39 Python scripts (no longer needed) | +-> #3 Delete queue processor (only existed for mem0 retry) | +-> #4 Simplify memory-writer.ts (remove 3-tier fallback) | +-> #5 Remove MEM0_API_KEY from CI/CD (no longer used) Root decision: #1 Cascade: 4 follow-on decisions, all lower risk than root ``` ## Reversible vs Irreversible Decisions Flag decisions by how hard they are to undo: ``` DECISION LOG #1 [REVERSIBLE] Use PostgreSQL for billing data Can migrate to another DB later. Schema is the contract, not the engine. #2 [REVERSIBLE] REST over GraphQL for billing API Can add GraphQL layer later without changing REST endpoints. #3 [IRREVERSIBLE] Store amounts in cents (integer) not dollars (float) All downstream systems will depend on integer representation. Changing later requires data migration across all consumers. ``` ### Decision-Router Board # Decision-Router Board A **decision-board** (Now/Next/Later triage + RICE) where every card also opens a full-screen **Execute** panel that routes the task to an ork execution strategy and emits a **plan-only** invocation. It is the bridge from "what to do" → "how to run it" → a copy-pasteable command. Use it (over the plain `decision-board.template.html`) when the plan is a **backlog the user must both prioritize and dispatch** — issues to triage, PRD phases to schedule, a wave of work to route. Plain prioritization with no execution step → use `decision-board.template.html`. A single linear flow → `user-story-player`. <2 decision signals → dashboard (the standard doesn't apply). Copyable exemplar: `$\{CLAUDE_PLUGIN_ROOT\}/shared/assets/playground-exemplars/decision-router.template.html` — swap the `CARDS` array, keep the engine. Real-data example: `docs/<branch-dir>/decision-router-board.html`. ## STEP A — seed CARDS from real data The board is data-driven via one `CARDS` array. Each card: ```js { id:'2475', // stable key (issue number / slug) ico:'🔧', ttl:'Re-architect InstructionsLoaded hooks', why:'one line — why it matters / the decision at stake', impact:5, effort:3, // 1–5 each → RICE + Impact/Effort meters rec:'now', // now | next | later (initial bucket) badges:[['risk0','zero-risk']] } ``` Sources (pick what the user gave you): | Source | How | |--------|-----| | GitHub issues | `gh issue list --json number,title,body,labels --limit 20` → one card each; `impact`/`effort` from labels or a quick estimate; `rec` from your triage | | PRD / spec | one card per requirement or phase; `why` = the acceptance criterion | | The plan brief | visualize-plan's STEP 1 execution phases → one card per phase | For defensible `impact`/`effort`/RICE, run the `prioritization` skill's RICE rubric rather than guessing — the board renders whatever scores you pass. ## STEP B — the Execute panel (already built into the engine) Each card's drawer offers five strategies. **They map 1:1 to real ork/Workflow tooling** — this mapping is the whole point: | Strategy | Emits / runs as | Reliability · cost | |----------|-----------------|--------------------| | single | `/ork:<skill>` (fans out ork agents internally) | ~85–95% · 1× | | workflow | the **Workflow** tool — `pipeline` or `orchestrator-worker` | ~80–90% · 1× | | nested | an ork lead agent → sub-agents (Task/Agent), recurse ≤depth | ~70–80% · ~1.5× | | teams | **Agent Teams** — implicit team, `Agent(name=)` + `SendMessage` mesh | ~60–70% · ~3× | | swarm | LLM council — parallel → blind review → chairman | ~50–65% · ~3–4× | Specialist picker = the **full 36-agent ork registry** (`all`/`none` bulk select). Caps are **structural, not arbitrary**: workflow is uncapped (parallel work queues past 16); nested 6 / teams 6 / swarm 7 because nesting is depth-bounded and mesh/council reliability collapses with N. Topology preview renders the chosen shape live. ## STEP C — the plan-only invocation (the bridge to execution) "Copy invocation" yields a **plan-only** instruction, e.g.: ``` Run a Workflow (pipeline) for "Re-architect InstructionsLoaded hooks" with ork:backend-system-architect, ork:test-generator. Plan-only: show me the script before executing. ``` Paste it back into Claude Code → it runs the chosen strategy, plan-first. Plan-only by design: the board decides *how*, the user approves before anything spawns. Never auto-execute from the board. ### Deep Dive Patterns (Tier 3) # Deep Dive Patterns These are Tier 3 sections rendered only on explicit request after the core 5 sections. ## [7] Cross-Layer Consistency Verify frontend/backend alignment by mapping endpoints to consumers: ``` CROSS-LAYER CONSISTENCY Backend Endpoint Frontend Consumer Status POST /invoices createInvoice() PLANNED GET /invoices/:id useInvoice(id) PLANNED GET /invoices InvoiceList.tsx MISSING !! ``` ### Rules - List every backend endpoint the plan introduces or modifies - Map each to its frontend consumer (component, hook, or API call) - Flag `MISSING !!` for any unmatched endpoint — these are gaps in the plan - Flag `ORPHANED !!` for frontend consumers calling endpoints not in the plan - Include status: EXISTING, PLANNED, MISSING, ORPHANED ## [8] Migration Checklist Generate an ordered runbook with explicit dependency constraints and time estimates: ``` MIGRATION CHECKLIST Sequential Block A (database): 1. [ ] Backup production database [~5 min] 2. [ ] Run migration: 001_add_invoices.sql [~30s] <- blocks #4 Parallel Block B (after #2): 3. [ ] Deploy API v2.1.0 [~3 min] 4. [ ] Update frontend bundle [~2 min] Sequential Block C (verification): 5. [ ] Smoke test [~2 min] 6. [ ] Monitor error rate 15 min [~15 min] ``` ### Rules - Group steps into sequential and parallel blocks - Show `<- blocks #N` for dependency constraints - Include time estimates for each step - Always start with a backup step for data-touching migrations - Always end with verification (smoke test + monitoring) - Use checkbox format `[ ]` for runbook usability ### Execution Swimlane Patterns # Execution Swimlane Patterns Temporal dependency diagrams showing parallel/sequential execution. ## Symbol Convention ``` === Active work (this lane is executing) --- Blocked / waiting for a dependency | Dependency line (vertical) + Junction (dependency meets lane) > Flow direction (lane endpoint) [N] Phase reference number ``` ## Basic Swimlane (2 lanes) ``` Backend ===[1: Schema]==[2: API]========================[4: Deploy]===> | | ^ | +--------blocks---------+ | | | | Frontend ------[Wait]--------[3: Components]=========[5: Integrate]+ === Active --- Waiting | Dependency Critical path: 1 -> 2 -> 4 (backend-bound) ``` ## Multi-Lane Swimlane (3+ lanes) ``` Database ===[1: Migrate]=====================================> | +---blocks---+---blocks---+ | | | Backend --------[Wait]------[2: API]=====[4: Deploy]=======> | ^ +--blocks--+ | | | | Frontend --------[Wait]------[Wait]-----[3: UI]==[5: Int.]==> | Tests --------[Wait]------[Wait]-----[Wait]---[6: E2E]===> === Active --- Waiting | Dependency Critical path: 1 -> 2 -> 3 -> 5 (longest chain) Parallel opportunity: Backend deploy (4) can run alongside Frontend UI (3) ``` ## Phase Detail Blocks Expand key phases with sub-steps: ``` Phase 2: API Endpoints [estimated: 2-3 hours] +--------------------------------------------------+ | 2a. Define Pydantic schemas (InvoiceCreate, etc.) | | 2b. Implement CRUD routes | | 2c. Add auth middleware to new routes | | 2d. Write route tests | +--------------------------------------------------+ Blocks: Phase 3 (UI needs API contract) Blocked by: Phase 1 (needs DB tables) ``` ## With Time Estimates ``` Timeline (estimated): 0h 1h 2h 3h 4h 5h 6h |---------|---------|---------|---------|---------|---------| Database [##1##] Backend [####2####] [##4##] Frontend [####3####][##5##] Tests [##6##] ▲ ▲ Start Done Estimated total: 6 hours (3.5h critical path + 2.5h parallel) Without parallelism: 9.5 hours Time saved by parallel execution: ~37% ``` ## Dependency Graph (DAG style) For complex dependency chains, use a directed acyclic graph: ``` EXECUTION ORDER (DAG) [1: Schema] | +---+---+ | | [2: API] [3: Indexes] | | +---+---+ | [4: Deploy API] | +---+---+ | | [5: UI] [6: Cache] | | +---+---+ | [7: Integration] | [8: E2E Tests] Parallelizable pairs: (2,3), (5,6) Serial bottleneck: 4 (both UI and cache depend on API deploy) ``` ## Conditional Execution When phases have success/failure branches: ``` [1: Migrate] --success--> [2: API] --success--> [3: Deploy] | | +--failure--> +--failure--> | | [1R: Rollback DB] [2R: Revert API] | | +-----> [ABORT] <------+ ``` ### Format Dispatch # Format Dispatch The format front-door (STEP 0.5) picks **how** to render; STEP 2 picks **which** sections. Dispatch maps the one plan-viz model to the chosen surface(s). ASCII is the floor — always rendered first, never blocked on an async job. ## Capability probe (run once, before the front-door question) Gate the format options by what's actually available, so the picker never offers a path that will fail: Use the established MCP-probe pattern (`Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/chain-patterns/references/mcp-detection.md")`) — not invented helpers: ```python ToolSearch(query="select:mcp__notebooklm-mcp__studio_create") # infographic gate ``` - **ascii** — always available (the floor). - **playground** — available if the `playground` skill is installed (ships with ork). - **infographic** — available if `mcp__notebooklm-mcp__studio_create` resolved via the `ToolSearch` above. If the server is undefined in `.mcp.json` or `nlm login` hasn't run, the tool won't resolve — treat infographic as unavailable. Hide unavailable options from the AskUserQuestion list and add a one-line install/auth hint instead of failing: | Unavailable | Hint to surface | |-------------|-----------------| | playground | "Playground needs the `playground` skill (ships with ork) — falling back to ASCII." | | infographic | "NotebookLM infographic needs the notebooklm MCP server reachable + `nlm login` — falling back to ASCII." | `All available` = the union of whatever passed the probe. If only ASCII passed, skip the question entirely and render ASCII. ## Dispatch table | Format | How | Output | Blocks? | |--------|-----|--------|---------| | ASCII + emojis | Native — render sections per `rules/section-rendering.md` | In chat | n/a (always first) | | Interactive playground | Classify archetype (§0 of the visual standard), build the plan brief, hand to the `playground` skill | `docs/<branch-dir>/plan-viz.html` | No — write then link | | NotebookLM infographic/slides | Build a source doc, run the notebooklm `studio_create(artifact_type=infographic\|slides)` flow | `.png`/slides artifact | **No — fire-and-notify** | | All available | Fan out: ASCII inline now + the others as they finish | all of the above | No | `<branch-dir>` = current branch with `/` → `--` (matches the PR Playground CI gate path, so the playground also satisfies that gate for free). > **Archetype before generation.** Most plan visualizations are a **DASHBOARD** (the default card grid). > But a plan that demonstrates a *user-facing flow* or a *prioritization/decision* should be a > **user-story-player** or **decision-board** — `Read("$\{CLAUDE_PLUGIN_ROOT\}/shared/rules/playground-visual-standard.md")` > for the §0 routing rule, the token/glass/motion spec, and the exemplars to adapt > (`shared/assets/playground-exemplars/`). Brief the `playground` skill with archetype + persona, not raw HTML. > > **Decision-router variant.** When the board is a *backlog the user must both prioritize and dispatch* > (issues to triage, PRD phases to schedule, a wave to route), use the **execution-router** board: each > card routes to an ork strategy (single/workflow/nested/teams/swarm) over the full 36-agent registry and > emits a **plan-only** invocation. Seeding recipe + strategy→tooling map: `Read("$\{CLAUDE_PLUGIN_ROOT\}/skills/visualize-plan/references/decision-router.md")`. ## Living-plan update mode A plan that executes over multiple sessions/waves is a **living plan**: one plan = ONE html file that carries its own state and gets updated in place. Exemplar: `living-plan.template.html` (§0 dashboard sub-route in the visual standard). The contract: 1. **Detect by SLUG, never by path.** Path-keyed detection is broken by design: the target path is derived from the branch name, so renaming the branch moves the path, the check misses, and the plan forks. That is not hypothetical — `langchain-ecosystem-currency` shipped as two files with the same slug and the same `updated` date, under `docs/chore--…` and `docs/research--…`. Run this **before authoring**, not after: ```bash # SLUG = the plan's stable slug (kebab-case, derived from the plan title — NOT the branch) bash "$SKILL_DIR/scripts/find-living-plan.sh" "$SLUG" ``` - **Exactly one hit** → you are UPDATING that file. Merge into it (step 2) wherever it lives. - **No hits** → you are AUTHORING. Write `docs/<branch-dir>/plan-viz.html` (step 5). - **More than one hit** → STOP. The plan already forked. Say so, name both paths, and ask which survives; `git mv` the survivor and delete the other in the same commit. Do not write a third. Renaming a branch is a `git mv` of the directory, never a new file. The slug is the identity; the path is an address that can change. 2. **Merge, never overwrite.** Parse the JSON, flip item `status` (`planned → in_progress → done`, or `dropped` with a changelog reason), append to `changelog` (append-only), bump `updated`. Removed work moves to `dropped`; items are never deleted. 3. **Evidence gate.** An item may only move to `done` when its `evidence` check ("done when: <command>") has actually been run this session. Done without evidence is a contract violation — leave it `in_progress` and say why. 4. **State renders, prose doesn't.** The "Now" column and wave counters are computed from item statuses by the file's own renderer. Update the JSON; do not hand-edit rendered progress. 5. **Git history is the timeline.** Each update is a normal commit; no side-channel progress files. 6. **The filename is `plan-viz.html`.** Not `index.html`, not a topic name. The spec has always said so and reality ran 5:1 against it (`index.html` ×79 vs `plan-viz.html` ×18, plus ~90 bespoke names), which is exactly what breaks slug lookup and leaves 191 artifacts unindexable. One filename, one glob, one `find-living-plan.sh` that works. Minimal state shape (v1): `\{lpp, slug, title, created, updated, score\{composite,target\}, waves[\{id,title,status\}], items[\{id,wave,title,impact,effort,risk,status,detail,evidence,owner\}], changelog[\{at,note\}]\}`. ## The plan brief (shared interchange, v1) All non-ASCII renderers consume the same compact markdown brief built in STEP 1 — one source of truth, no per-format recomputation: ``` # Plan: () Risk: | Confidence: | Reversible until ## Before/After Architecture → ## Sections [selected sections, each as a short titled block] ``` > v2 (separate follow-up issue): replace this markdown brief with a json-render plan-viz Zod catalog so ASCII / HTML / PDF / OG-image render from one typed spec with parity (mirrors `assess`'s `assess-dashboard.json`). The markdown brief is a stable v1 interface, not a throwaway — v2 adds a typed layer behind it. ## ASCII floor rule Always render the ASCII view **first and inline**, even when a richer format is selected. Rationale: - NotebookLM `studio_create` is async — never `await` it inside the skill. Kick it off, then poll `studio_status` on a **bounded budget: up to 10 checks at 30s intervals** (~5 min ceiling). On `complete`, surface the artifact link via a hook `terminalSequence` (CC 2.1.141+ — the no-round-trip path, preferred) or `PushNotification`; on timeout, surface a "still rendering — open it in NotebookLM directly" link instead of hanging. The user already has the ASCII answer, so this never blocks. - If a richer renderer fails mid-flight, the user still has a complete visualization. ## Progressive upgrade (STEP 5 action) After ASCII renders, offer "upgrade this to [playground | infographic]" so format is also a *post-hoc* choice, not only a front-door one. Reuses the same plan brief — no recomputation. ### Risk Dashboard Patterns # Risk Dashboard Patterns Reversibility timelines and pre-mortem scenarios. ## Reversibility Timeline Shows each phase's undo capability. The point of no return is the most important signal. ### Standard Format ``` REVERSIBILITY TIMELINE Phase 1 [================] FULLY REVERSIBLE (add column, nullable) Phase 2 [================] FULLY REVERSIBLE (new endpoint, additive) Phase 3 [============....] PARTIALLY (backfill data, can truncate) --- POINT OF NO RETURN --- Phase 4 [........????????] IRREVERSIBLE (drop old column, data lost) Phase 5 [================] FULLY REVERSIBLE (frontend toggle via flag) Recommendation: Add backup step before Phase 4 ``` ### Fill Pattern Legend ``` [================] FULLY REVERSIBLE — Can undo completely, no data loss [============....] PARTIALLY — Can undo, but some manual cleanup needed [========........] DIFFICULT — Requires backup restore or significant effort [....????????????] IRREVERSIBLE — Cannot undo, data permanently changed ``` ### Compact Format (for simple plans) ``` Reversibility: Phase 1 [SAFE] -> Phase 2 [SAFE] -> Phase 3 [PARTIAL] -> Phase 4 [IRREVERSIBLE] ^ Point of no return ``` ### With Rollback Instructions ``` REVERSIBILITY + ROLLBACK Phase 1: Add users.billing_address column Reversibility: FULL Rollback: ALTER TABLE users DROP COLUMN billing_address; Time: <1 min | Data loss: NONE Phase 2: Deploy billing API endpoints Reversibility: FULL Rollback: Revert deployment to previous version Time: ~3 min | Data loss: NONE Phase 3: Backfill billing_address from legacy table Reversibility: PARTIAL Rollback: UPDATE users SET billing_address = NULL WHERE ...; Time: ~10 min | Data loss: backfilled data only Phase 4: Drop legacy_billing table Reversibility: NONE Rollback: Restore from backup (Phase 0 snapshot required) Time: ~30 min | Data loss: ALL legacy billing if no backup ``` ## Pre-Mortem Scenarios Frame risks as "what already went wrong" narratives. More memorable than probability tables. ### The one rule: state a MECHANISM, not a category A category names *what kind* of bad thing could happen. A mechanism names *what runs, in what order, producing what bad state*. Only the second is actionable, because only a mechanism can be contained. This is the measured failure mode of this section, not a style preference. A 2026-08-04 eval graded real output and the grader's words were: *"names categories … but describes no causal sequence of how failure occurs."* ``` ❌ CATEGORY "Migration risk — the schema change could cause problems" ❌ CATEGORY "Manual JWT validation" ← a topic heading, not a failure ✅ MECHANISM "P2 ships while an in-flight retry queue still points at the inline charge path, so the same invoice is charged twice." ``` Write it as `<trigger> → <sequence> → <bad end state>`. The test: can a reader say *when* it fires and *what state it leaves behind*? If it reads like a section heading, it is still a category. Containment must reference that specific mechanism. "Add tests" is not containment; "idempotency key derived from invoice id, asserted before P2 merges" is. Note how each scenario below names a trigger and an outcome, never just a topic. ### Standard Format (3 scenarios) ``` PRE-MORTEM: This plan failed because... 1. MOST LIKELY: Cache served stale prices after Stripe webhook Probability: HIGH | Impact: HIGH Mitigation: Add cache invalidation hook on webhook receipt Rollback: Clear Redis cache (30s recovery) Detection: Monitor cache hit rate, alert on stale-age > 60s 2. MOST SEVERE: Migration ran on replica before primary Probability: LOW | Impact: CRITICAL Mitigation: Run migration with explicit --primary flag, verify replication lag Rollback: Cannot cleanly roll back (need full backup restore) Detection: Check pg_stat_replication before and after 3. MOST SUBTLE: Frontend shows billing tab to free-tier users Probability: MEDIUM | Impact: MEDIUM Mitigation: Add feature flag check in BillingTab component Rollback: Disable feature flag (instant) Detection: QA checklist for each user tier ``` ### Tabular Format (for quick scanning) ``` PRE-MORTEM RISK TABLE +======================+========+==========+========================+=============+ | Scenario | Prob. | Impact | Mitigation | Rollback | +======================+========+==========+========================+=============+ | Stale cache after | HIGH | HIGH | Cache invalidation | Clear Redis | | webhook update | | | on webhook receipt | (30s) | +----------------------+--------+----------+------------------------+-------------+ | Migration on replica | LOW | CRITICAL | --primary flag + | Full backup | | before primary | | | check replication lag | restore | +----------------------+--------+----------+------------------------+-------------+ | Billing tab shown | MEDIUM | MEDIUM | Feature flag in | Disable | | to free-tier users | | | BillingTab component | flag (0s) | +----------------------+--------+----------+------------------------+-------------+ ``` ## Risk-Impact Quadrant For plans with many risk factors, use a 2x2 grid: ``` HIGH IMPACT | MONITOR CLOSELY | ACT NOW | * API versioning | * schema migration * env config | * cache invalidation | ──────────────────────+─────────────────── HIGH LIKELIHOOD | ACCEPT | MITIGATE | * docs update | * feature flag timing * logging format | * DNS propagation | LOW IMPACT Priority: ACT NOW > MITIGATE > MONITOR > ACCEPT ``` ## Cascading Failure Analysis For distributed systems, show how one failure propagates: ``` FAILURE CASCADE: Database connection pool exhausted [Pool exhausted] --> [API timeouts] --> [Frontend 504s] --> [User complaints] | | | v v v Detection: Detection: Detection: Connection p95 latency Error rate count alert > 5s alert > 1% alert (30s) (2 min) (5 min) Total detection time: 30s (if pool alert configured) Blast radius without alert: ~5 min until user-visible ``` ### Visualization Tiers # Visualization Tiers Plan-viz uses three tiers of progressive disclosure. Tier 1 is always shown; Tier 2 sections are shown on request; Tier 3 deep dives are on-demand. ## Tier 1: Header (Always Rendered) Use `assets/tier1-header.md` template. Fill from gathered data: ``` 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] ``` ### Computing Header Fields - **Risk level** = highest risk across all phases (LOW/MEDIUM/HIGH/CRITICAL) - **Confidence** = LOW if >50% of changes are in untested code, MEDIUM if mixed, HIGH if well-tested paths - **Reversible until** = last phase before an irreversible operation (DROP, DELETE data, breaking API change) ## Tier 2: Core Sections (On Request) Six numbered sections, each answering a specific reviewer question. Section [0] is the default lead: | Section | Question Answered | Pattern Reference | |---------|------------------|-------------------| | [0] Before/After Arch | What changes about the shape of the system? | `before-after-arch-patterns.md` | | [1] Change Manifest | What files change and how? | `change-manifest-patterns.md` | | [2] Execution Swimlane | What runs in parallel? What blocks what? | `execution-swimlane-patterns.md` | | [3] Risk Dashboard | What can go wrong? When is it irreversible? | `risk-dashboard-patterns.md` | | [4] Decision Log | What non-obvious choices were made? | `decision-log-patterns.md` | | [5] Impact Summary | What are the raw numbers? | `assets/impact-dashboard.md` | ## Tier 3: Deep Dives (On Demand) | Section | Question Answered | Reference | |---------|------------------|-----------| | [6] Blast Radius | How far do changes ripple? | `blast-radius-patterns.md` | | [7] Cross-Layer Consistency | Are frontend/backend aligned? | `deep-dives.md` | | [8] Migration Checklist | What's the ordered runbook? | `deep-dives.md` | --- ## Examples (3) ### Worked run 1 — default dashboard # Worked run 1 — the default path The scenario is the same one committed as sample state in `playground-exemplars/plan-dashboard.template.html`, so the example and the template reinforce each other. Read this before authoring your first plan visualization. ## Input ``` $ git branch --show-current feat/billing-redesign $ /ork:visualize-plan ``` No flags. So: source auto-detected, all six sections, ASCII only, one question at the end. **Zero questions before the first render.** ## STEP 0 — detect (no question, detection was unambiguous) ``` $ bash scripts/detect-plan-context.sh branch: feat/billing-redesign -> main issue: #234 (from branch-linked PR body "Closes #234") commits: 6 ahead files: 7 changed ``` ## STEP 1 — gather ``` $ bash scripts/analyze-impact.sh added: 4 files +1000 modified: 2 files +240 -272 deleted: 1 file -214 tests: 2 files touched ``` Explore agent maps components at `git show origin/main:<path>` (base) vs the working tree (head). Both maps feed section [0] **and** the plan brief that any richer format will consume. ## STEP 2 — tier 1 header (always) ``` PLAN: Billing module redesign (#234) | 4 phases | 7 files | +1240 -486 lines Risk: MEDIUM | Confidence: HIGH | Reversible until P3 (schema migration) Branch: feat/billing-redesign -> main [0] Before/After [1] Changes [2] Execution [3] Risks [4] Decisions [5] Impact [all] ``` ## STEP 4 — sections (all six, no picker) ### [0] Before/After <!-- ascii-lint-disable: balanced-corners --> ``` BASE (origin/main) HEAD (working tree) api/routes/billing.ts api/routes/billing.ts └ stripe.charge() inline -> └ delegates to BillingService [~] services/BillingService.ts [+] └ providers/StripeProvider.ts [+] lib/legacy-invoice.ts [-] db/schema/invoices db/schema/invoices (+ provider_ref) [~] ``` ### [1] Change Manifest <!-- ascii-lint-disable: balanced-corners --> ``` services/ ├── BillingService.ts [A] +412 ** new file └── providers/StripeProvider.ts [A] +286 ** new file api/ └── routes/billing.ts [M] +174 -231 !! 3 handlers rewritten db/ └── migrations/0042_provider_ref.sql [A] +38 !! hot table tests/ ├── billing/service.test.ts [A] +264 ** new file └── billing/routes.test.ts [M] +66 -41 lib/ └── legacy-invoice.ts [D] -214 ~~ replaced by BillingService Legend: [A]dd [M]odify [D]elete !! Risk ** New Summary: +1240 -486 | 4 new | 2 modified | 1 deleted ``` ### [2] Execution Swimlane ``` Service ===[P1: Extract]===[P2: Provider]===============================> | +---blocks---+ | Schema -------[Wait]------------[Wait]----[P3: Migrate]====+ | +--blocks--+ | Cleanup -------[Wait]------------[Wait]--------[Wait]-----[P4: Delete]==> === Active --- Waiting | Dependency Critical path: P1 -> P2 -> P3 -> P4 (fully sequential — no parallel opportunity) ``` ### [3] Risk Dashboard ``` REVERSIBILITY TIMELINE P1 [================] FULLY REVERSIBLE (pure refactor, tests green) P2 [================] FULLY REVERSIBLE (provider seam, additive) P3 [============....] PARTIALLY (nullable column, can drop) --- POINT OF NO RETURN --- P4 [....????????????] IRREVERSIBLE (legacy reader deleted) PRE-MORTEM (3 scenarios) R1 CRITICAL Double-charge during cutover How: P2 ships while an in-flight retry queue still points at the inline charge path; the same invoice is charged twice. Containment: idempotency key derived from invoice id, asserted before P2 merges. R2 SERIOUS Migration locks the invoices table How: 0042 adds NOT NULL with a default; Postgres rewrites 4.2M rows. Containment: land nullable, backfill in batches, NOT NULL in a later migration. R3 WARNING Legacy reader still live at P4 How: an ungrepped cron job imports legacy-invoice and throws after the delete. Containment: 7-day telemetry gate on legacy read count == 0. ``` ### [4] Decision Log · [5] Impact ADR-lite per decision (Context / Decision / Alternatives / Tradeoff), then the impact table. Both are rendered in full in the HTML; see the `plan-state` island in the template. ## STEP 5 — the one question ``` What next? › Interactive dashboard (Recommended) docs/feat--billing-redesign/plan-viz.html Drill deeper blast radius / cross-layer / migration checklist Generate GitHub issues one per execution phase Done ``` Picking the dashboard copies `plan-dashboard.template.html` and replaces **only** the `plan-state` island with the data already gathered — no recomputation, no hand-written CSS. ## What "good" looked like here - Every number came from `analyze-impact.sh`, not estimated. - [0] compared `git show origin/main:<path>` against the working tree, not two guesses. - Each risk carries a *mechanism* ("how"), not a category. "Migration is risky" is not a risk. - The point of no return is stated once, loudly, and matches the reversibility field in the header. - The HTML reused the template; the only authored content was JSON. ### Worked run 2 — living plan, update mode # Worked run 2 — updating a living plan A plan that executes over multiple sessions is a **living plan**: one plan = ONE file, updated in place. This run is the *second* session on that plan. The whole point is that it must not create a second file. ## Input ``` $ git branch --show-current chore/dep-currency-sweep # NOTE: renamed since session 1, which was on research/dep-currency $ /ork:visualize-plan ``` The branch rename is the interesting part. Path-keyed detection would look for `docs/chore--dep-currency-sweep/plan-viz.html`, find nothing, and author a **second** plan. That is exactly how slug `langchain-ecosystem-currency` ended up committed twice. ## STEP 4b — detect by SLUG, before authoring anything ``` $ bash scripts/find-living-plan.sh "dep-currency-sweep" docs/research--dep-currency/plan-viz.html $ echo $? 0 ``` Exit 0, one hit → **UPDATE that file, wherever it lives.** Not the branch-derived path. | Exit | Meaning | Action | |---|---|---| | 0 | one match | Merge into the printed path | | 1 | no match | Author `docs/<branch-dir>/plan-viz.html` | | 2 | **already forked** | STOP. Name both paths, ask which survives, `git mv` + delete in one commit | ## The merge (never an overwrite) Read the existing `lpp-state`, mutate the JSON, leave the renderer alone. ```diff { "id": "i3", "wave": "w2", "title": "Bump langchain to 0.4.x", - "status": "in_progress", + "status": "done", "evidence": "pnpm -r why langchain shows 0.4.x only" }, { "id": "i4", "wave": "w2", "title": "Drop the pydantic v1 shim", - "status": "planned", + "status": "in_progress", "evidence": "grep -r 'pydantic.v1' src/ returns nothing" }, "changelog": [ + { "at": "2026-08-04", "note": "i3 done (verified via pnpm why). i4 started." }, { "at": "2026-07-25", "note": "v1 authored." } ] ``` Then `git mv docs/research--dep-currency docs/chore--dep-currency-sweep` so the path catches up with the branch. **The slug never changes.** The slug is identity; the path is an address. ## The evidence gate is not a formality `i3` moved to `done` only because the check was actually run **this session**: ``` $ pnpm -r why langchain langchain 0.4.2 (1 dependent) ``` Compare with the item that did *not* move: ``` { "id": "i5", "wave": "w2", "title": "Regenerate the lockfile", "status": "in_progress", # NOT done — evidence never run "evidence": "pnpm install --frozen-lockfile exits 0" }, ``` Say so out loud: *"i5 looks finished but I did not run `pnpm install --frozen-lockfile`, so it stays in_progress."* Marking done without evidence is a contract violation, not a rounding error. ## The fork case (exit 2) ``` $ bash scripts/find-living-plan.sh "langchain-ecosystem-currency" docs/chore--langchain-ecosystem-currency/plan-viz.html docs/research--langchain-ecosystem-currency-2026-07-25/plan-viz.html FORKED: 2 files share slug 'langchain-ecosystem-currency' — reconcile before writing. $ echo $? 2 ``` Do **not** write a third file, and do not silently pick one. Report both paths with their `updated` dates and item counts, ask which survives, then reconcile in a single commit. Gated by `tests/orphans/test-duplicate-living-plans.sh`, which fails on committed forks. ## What "good" looked like here - Detection ran **before** authoring, and keyed on the slug, not the branch-derived path. - The merge was a JSON mutation; no rendered progress was hand-edited. - `changelog` was appended to, never rewritten; nothing was deleted (removed work → `dropped`). - One item was explicitly left `in_progress` with the reason stated, rather than rounded up to done. - The directory was `git mv`'d to follow the branch, keeping one file for one slug. ### Worked run 3 — --quick # Worked run 3 — `--quick` `--quick` exists because the full path costs an Explore agent, a six-task dependency graph, and a question. Sometimes the honest answer to "what does this branch touch?" is a header and two sections, and paying for the rest is why fast questions leaked to `/ork:glyph` and to hand-written HTML instead. ## Input ``` $ /ork:visualize-plan --quick ``` ## What is skipped | Step | Full run | `--quick` | |---|---|---| | TaskCreate block | 6 tasks + dependency graph | skipped entirely | | STEP -1 memory search | yes | skipped | | STEP 1 Explore agent | base-vs-head component map | skipped | | Sections | all six | `[1]` Changes + `[5]` Impact | | STEP 5 question | one | none | | Memory write | yes | skipped | Everything that survives is fed by `scripts/analyze-impact.sh` alone. No sub-agent runs, so there is no worktree, no model spend beyond this turn, and nothing to wait on. ## Output ``` PLAN: Working branch (feat/billing-redesign) | 7 files | +1240 -486 lines Risk: MEDIUM (1 migration, 1 delete) | Branch: feat/billing-redesign -> main ``` <!-- ascii-lint-disable: balanced-corners --> ``` services/ ├── BillingService.ts [A] +412 ** new file └── providers/StripeProvider.ts [A] +286 ** new file api/ └── routes/billing.ts [M] +174 -231 !! 3 handlers rewritten db/ └── migrations/0042_provider_ref.sql [A] +38 !! hot table tests/ ├── billing/service.test.ts [A] +264 ** new file └── billing/routes.test.ts [M] +66 -41 lib/ └── legacy-invoice.ts [D] -214 ~~ replaced by BillingService Legend: [A]dd [M]odify [D]elete !! Risk ** New Summary: +1240 -486 | 4 new | 2 modified | 1 deleted ``` ``` IMPACT Added 4 files +1000 Modified 2 files +240 -272 Deleted 1 file -214 NET +754 Tests 2 files touched | API surface 1 additive field | Deps none ``` Then it stops. No "what next?". ## What `--quick` must NOT do - **Do not fabricate the fields it skipped.** Risk here is derived from the file list (a migration and a delete are visible without an agent). Confidence and reversibility are *not* shown, because computing them honestly needs the analysis `--quick` declined to run. A blank field beats a guessed one. - **Do not write to memory.** A quick look is not a decision worth persisting; storing it pollutes the cross-session comparison the full run depends on. - **Do not silently upgrade.** If the branch turns out to need real analysis, say so in one line ("7 files including a schema migration — worth a full run?") and let the user ask. ## When to use the full run instead Anything where the *judgment* is the deliverable: reviewing a plan before committing to it, comparing approaches, assessing blast radius, or producing an artifact someone else will read. `--quick` answers "what changed"; the full run answers "should we do this, and in what order".