visualize-plan

计划可视化

将计划中的更改呈现为结构化的 ASCII 可视化内容，并附上风险分析、执行顺序和影响指标。每个部分都回答一个特定的审阅者问题。

**核心原则：**将判断融入可视化，而非装饰。

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

参数解析

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]

提问预算：首次渲染前为零

此技能过去会在渲染出第一个字符前，先提出三个阻塞性问题（依次询问来源、格式和章节），渲染后还会再问第四个问题。这就是快速路径转而使用 glyph 和手写 HTML 的原因。

渲染 ASCII 不需要知道格式答案——无论用户选择什么，ASCII 底线规则都会先渲染。因此，提前提问毫无益处，只会多耗费一次往返。现行规则如下：

决策	时机	方式
来源	之前	自动检测。仅当检测确实存在歧义时才询问（步骤 0）。
章节	从不	默认选择全部。第 1 层级标题就是渐进式披露层。
格式	ASCII 之后	渲染后提问一次（步骤 5），并与深入探索的问题合并。

--quick 连这一次提问也会跳过。

预算：最多使用 1 个 Explore Agent，并在渲染后提问一次（步骤 5）；到达终点线或第一个上限时，以先到者为准，然后停止并报告。

---

关键：任务跟踪

**--quick 会跳过整个区块。**15 秒的渲染不需要依赖关系图；任务开销会超过实际工作量。

# 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

步骤 -1：检查记忆中的过往计划

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

步骤 0：检测或澄清计划背景

首先，尝试运行 scripts/detect-plan-context.sh 自动检测：

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

这会输出分支名称、问题编号（如有）、提交数量和文件更改摘要。

如果自动检测找到明确的计划（分支上的提交与 main 存在分歧，或参数中包含问题编号），则继续执行步骤 1。

如果存在歧义，则使用 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
  }]
)

---

步骤 0.5：探测格式（静默执行——不在此处提问）

现在探测功能支持情况，以便步骤 5 只提供实际可用的选项。**此步骤不要提问。**完整流程见：Read("references/format-dispatch.md")。

使用既定的 MCP 探测模式——Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/mcp-detection.md")——不要临时编写检查：

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

将可用选项记录为 AVAILABLE：始终包含 ascii（底线）；如果安装了 playground 技能，则包含 playground（随 ork 一起提供）；如果上文解析出 studio_create（服务可访问且已完成 nlm login），则包含 infographic。此外，如果解析出 /dataviz 技能，则通过其表单启发式和经过验证的调色板，升级非 ASCII 格式中的图表标记；如果未解析出该技能，图表则保留为 ASCII 卡片——dataviz 并非必需。

随后无需提问即可设置 FORMATS：

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 底线规则：**无论如何，都会优先内联渲染 ASCII——而且由于它不受格式选择影响，因此可以将选择推迟到步骤 5，此时不会增加任何成本。切勿对异步 NotebookLM 任务使用 await。

---

步骤 1：收集数据

运行 scripts/analyze-impact.sh 以获取精确计数：

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

此脚本会生成：按操作类型（新增／修改／删除）划分的文件数、行数、受影响的测试文件，以及依赖项更改。

--quick 到此为止——仅影响分析脚本就足以生成标题、[1] 更改和 [5] 影响。不使用 Explore Agent，不生成更改前后映射，也不写入记忆。

为了理解架构层面的情况，并生成默认的更改前后章节 [0]，请启动一个 Explore Agent，分别映射基础版本和当前版本的组件图：

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
)

如果差异涉及前端（*.tsx／*.css／路由文件），还需运行一次 design-context-extract，将设计界面纳入更改前后对比。模式见：Read("references/before-after-arch-patterns.md")。

根据这些数据生成一份精简的计划简报（Markdown）——所有非 ASCII 格式都会使用这份统一的中间内容（参见 format-dispatch.md）。

---

STEP 2：呈现 Tier 1 标题（始终）

使用 assets/tier1-header.md 模板。加载 Read("references/visualization-tiers.md")，以计算字段（风险等级、置信度、可逆性）。

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：选择章节（不提问 — 默认全部呈现）

呈现全部六个章节。 它们就是内容；在审阅者还没看到任何内容之前就询问要呈现哪些章节，是让审阅者先做选择。Tier 1 标题已经承担了渐进式披露的作用；没有内容可说的章节会附上一行理由后跳过（不凑字数），因此“全部”绝不意味着“臃肿”。

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

只要 Explore 映射显示存在结构性变化，就由章节 [0] 前后对比领头；否则附上一行说明后跳过。如果用户在提示词中指定了特定章节（“只看风险”），请遵从，但不要主动询问。

---

STEP 4：呈现请求的章节

按照 rules/section-rendering.md 中的规范呈现每个请求的章节。使用对应参考资料中的 ASCII 模式：

章节	参考资料	关键规范
[0] 前后架构对比	（加载 references/before-after-arch-patterns.md）	并排展示 base 与 head；标记 [+]/[~]/[-]；若没有结构性变化则跳过
[1] 变更清单	（加载 references/change-manifest-patterns.md）	每个文件标记 [A]/[M]/[D] 和 +N -N
[2] 执行泳道图	（加载 references/execution-swimlane-patterns.md）	=== 表示活动，--- 表示阻塞，| 表示依赖
[3] 风险仪表板	（加载 references/risk-dashboard-patterns.md）	可逆性时间线 + 3 个事前验尸
[4] 决策日志	（加载 references/decision-log-patterns.md）	轻量 ADR：上下文/决策/备选方案/权衡
[5] 影响摘要	（加载 assets/impact-dashboard.md）	表格：新增/修改/删除/净值 + 测试/API/依赖项

---

步骤 4b：分发到相应格式

将选定章节渲染为步骤 0.5 中选定的 FORMATS。ASCII 始终优先渲染／内联呈现——其他格式使用同一份计划摘要。完整的表格和委派模式：Read("references/format-dispatch.md")。

格式	操作
ASCII	原生渲染（上文）——始终执行，这是最低要求
Playground	判断所属原型（见下文），然后将计划摘要交给 playground 技能 → 写入 docs/<branch-dir>/plan-viz.html，再用 page-serve docs/<branch-dir>/plan-viz.html 提供服务，并将打印出的 url= 放入回复的 Open 部分（绝不能只给裸路径，也不能手动启动 http.server）
Infographic	运行 notebooklm 的 studio_create(artifact_type=infographic|slides) 流程——触发后通知，轮询 studio_status，绝不等待完成
All	立即内联呈现 ASCII + 将其余格式作为链接，完成后提供
Charts（Playground／Infographic 中的标记）	对包含定量标记的章节——[3] 风险、[5] 影响、[6] 爆炸半径——通过 /dataviz（choosing-a-form）选择图表形式，通过其 6 项检查公式选择调色板，然后运行 validate_palette.js。验证器失败或缺少 /dataviz 时，回退到 ASCII 卡片布局。Chrome 保留 ork 令牌（playground-visual-standard.md 的 §2）；只有数据标记使用经过验证的调色板。参见 ${CLAUDE_PLUGIN_ROOT}/shared/rules/chart-encoding-standard.md。

<branch-dir> = 将分支名中的 / 替换为 --（与 PR Playground 门禁检查的路径相同）。文件名始终为 plan-viz.html——不是 index.html，也不是主题名称。只有使用同一个名称，slug 查找和制品库才能正常工作。

**Playground 原型：**计划可视化通常属于 DASHBOARD——截至 2026-08，它已是拥有模板的一等原型，不是可以随意发挥的通行证。复制 shared/assets/playground-exemplars/plan-dashboard.template.html 并替换 plan-state 区块；不要随意手写 CSS。它自带 §2 令牌、粘性一级标题、<details> 章节 [0]–[5]、每个图表对应的表格副本、复制提示词栏和减少动态效果门控。 如果计划展示的是面向用户的流程或优先级排序／决策，则改用 user-story-player 或 decision-board 原型。应用 Read("${CLAUDE_PLUGIN_ROOT}/shared/rules/playground-visual-standard.md") 中的 §0 路由规则，并在宣布完成前运行其中的 §10 自审——包括 DASHBOARD 各项检查。

要分发的内容是待办事项？ 如果计划是用户必须确定优先级并路由到执行的待办事项， 请使用 decision-router 变体——每张卡都会路由到一个 ork 策略，并生成仅包含计划的调用：Read("references/decision-router.md")。

持续更新的计划（多轮次）？ 如果计划会在多个会话／轮次中执行，或可通过命令验证是否完成，请使用 living-plan 示例（living-plan.template.html）：playground 会嵌入一个 lpp-state JSON 块，每个条目都包含一项“完成条件”证据检查，进度则根据状态渲染。

更新模式——通过 SLUG 检测，绝不通过路径检测。 路径由分支名称派生，因此分支 重命名会导致路径变化，而按路径检查会悄悄将计划分叉到第二个文件中。编写前运行查找器：

bash "$SKILL_DIR/scripts/find-living-plan.sh" "$SLUG"   # 0=更新现有计划 · 1=新建计划 · 2=已分叉，停止

退出码为 0 时，将更改合并到它打印出的文件中（翻转状态、追加变更日志、将移除的条目移至已丢弃项），无论该文件位于何处。退出码为 2 时，不要写入第三个文件——列出两个路径并询问应保留哪个。完整规范：Read("references/format-dispatch.md") §Living-plan 更新模式。由 tests/orphans/test-duplicate-living-plans.sh 执行门禁检查。

---

STEP 5：提供操作——唯一的问题

这是默认运行中唯一会阻塞流程的问题，其中包含格式选择；过去这个选择会在 STEP 0.5 阻塞流程。使用 --quick 时，或格式已通过标志设置且没有剩余可选项时，完全跳过此步骤。 根据 STEP 0.5 探测实际发现的内容构建选项列表——绝不提供无法成功执行的路径。

options = []
if "playground" in AVAILABLE and "playground" not in FORMATS:
    options.append({"label": "Interactive dashboard (Recommended)",
                    "description": "Single-file HTML at docs/<branch-dir>/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}])

受上限限制未能显示的内容仍可通过提问访问——菜单只是捷径，并非全部功能面。其中之一是 Write to designs/{branch}.md（模板：assets/plan-report.md）。

升级时复用 STEP 1 中构建的计划概要——无需重新计算 （参见 references/format-dispatch.md）。如果没有更丰富的内容可用，问题将退化为深入探讨／问题／完成。

写入文件： 使用 assets/plan-report.md 模板，将完整报告保存到 designs/{branch-name}.md。

生成问题： 为每个执行阶段创建一个 GitHub issue，标题为 [{component}] {phase_description}，添加标签（组件 + risk:{level}）和里程碑，正文取自计划各部分，并包含阻塞项引用。

存入记忆： 将计划摘要保存到知识图谱，以便日后比较：

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}"
  ]
}])

---

深入探讨（第 3 级，按需提供）

用户选择“深入探讨”时可用。加载 Read("references/deep-dives.md")，查看跨层模式和迁移模式。

章节	展示内容	参考
[6] 影响范围	影响的同心环（直接 -> 传递 -> 测试）	（加载 references/blast-radius-patterns.md）
[7] 跨层一致性	前端／后端端点对齐与差异检测	（加载 references/deep-dives.md）
[8] 迁移清单	包含顺序／并行区块和时间估算的有序运行手册	（加载 references/deep-dives.md）

---

核心原则

原则	应用
渐进式披露	始终显示第 1 级标题，按需显示各章节
重判断，轻装饰	每个章节都回答一个评审者的问题
重精确，轻估算	使用脚本统计文件数／行数
坦诚说明不确定性	置信度、事前验尸、权衡成本
输出可执行	写入文件、生成问题、深入探讨
反低质内容	不使用泛泛的过渡语、不假装精确、不保留无用章节

规则速查

规则	影响	覆盖内容
section-rendering（加载 rules/section-rendering.md）	高	全部 6 个核心章节（[0]–[5]）的渲染约定
ASCII 图示	中	通过 glyph skill（框线图、文件树、工作流）

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
visualization-tiers.md	渐进式披露层级和标题字段计算
change-manifest-patterns.md	变更清单 ASCII 模式
execution-swimlane-patterns.md	执行泳道 ASCII 模式
risk-dashboard-patterns.md	风险仪表盘 ASCII 模式
decision-log-patterns.md	决策日志 ASCII 模式
blast-radius-patterns.md	影响范围 ASCII 模式
deep-dives.md	跨层一致性和迁移清单
format-dispatch.md	输出格式能力探测、ASCII 底线规则，以及委派给 playground/notebooklm
before-after-arch-patterns.md	各输出格式的章节 [0] 变更前／后架构

示例（首次运行前先读一个）

完整的实操运行示例——真实输入、真实 ASCII 输出、真实生成的产物。其中的 ASCII 模式与 references/*-patterns.md 完全一致，可以直接参照使用。

文件	展示内容
examples/01-dashboard-run.md	默认流程的端到端示例：检测 → 收集 → 标题栏 → 全部六个章节 → 一个问题 → 生成的 HTML。场景与 plan-dashboard.template.html 中的示例状态相同。
examples/02-living-plan-update.md	重命名分支上的更新模式：按 slug 检测、JSON 合并、证据门槛，以及退出码为 2 时的分叉情况。
examples/03-quick-run.md	--quick：会跳过什么、输出是什么样子，以及绝不能捏造什么。

资源

按需使用 Read("assets/<file>") 加载：

文件	内容
plan-report.md	完整的 mustache 风格报告模板
impact-dashboard.md	影响表格模板
tier1-header.md	5 行摘要模板

质量标准

满足以下所有条件即为完成：

• Tier 1 标题栏始终包含所有字段——风险、置信度、可逆性、分支以及文件数和行数。
• 文件数和行数来自 scripts/analyze-impact.sh，不能估算或猜测。
• 每个渲染的章节都回答其评审问题；没有内容的章节应跳过，并用一行说明原因，绝不填充无关内容。
• 章节 [3] 按阶段 ID 明确指出不可逆转点（--- POINT OF NO RETURN (after P3) ---），不能含蓄带过；每个事前复盘都必须说明机制——触发条件、执行顺序、导致的错误状态——而非只列类别。“迁移风险”是一个标题；“P2 发布时，仍有正在处理的重试队列指向内联扣款路径，导致同一张发票被扣款两次”才是事前复盘。这是本章节衡量的失败模式，而非风格偏好：rules/section-rendering.md §[3] 规定了两项均可证伪的测试。
• 章节 [0] 的 Before/After 对比基线（git show origin/main:<path>）与 head（工作树），并为每个节点标记 [+]/[~]/[-]；没有结构性变化时，应跳过并附上说明。
• 无论选择何种格式，都先以内嵌方式渲染 ASCII；任何异步格式（信息图）都应立即启动并通知，绝不等待其完成。
• 计划摘要会保存到记忆知识图谱，以便跨会话比较（--quick 模式下跳过）。
• 首次渲染前不得有任何阻塞性问题。 自动检测来源（仅在确实存在歧义时提问），默认包含所有章节，并在 ASCII 基础版已显示后再选择格式——每次运行最多提问一次，--quick 模式下不提问。
• Playground 输出应以 plan-dashboard.template.html 为起点（或以 §0 路由规则选定的 living-plan / player / board 示例为起点），绝不手写 CSS；并通过 §10 自审，包括 DASHBOARD 行。
• 编写前应通过 scripts/find-living-plan.sh 按 slug 查找 living plan，这样现有计划会原位更新，而不是分叉成第二个文件。

相关技能

• ork:implement - 执行计划变更
• ork:explore - 了解当前架构
• ork:assess - 评估复杂度与风险
• ork:memory - 搜索以往的计划可视化
• ork:remember - 保存计划决策以供日后参考