plan-viz

计划可视化

将计划变更呈现为结构化 ASCII 可视化内容，包含风险分析、执行顺序和影响指标。每个部分都回答一个具体的评审者问题。

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

/ork:plan-viz                          # Auto-detect from current branch
/ork:plan-viz billing module redesign  # Describe the plan
/ork:plan-viz #234                     # Pull from GitHub issue

参数解析

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)

---

步骤 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", "markdown": "```\nBranch Diff Analysis\n────────────────────\n$ git diff main...HEAD\n\n→ File change manifest (+A, M, -D)\n→ Execution swimlane by phase\n→ Risk dashboard + pre-mortems\n→ Impact summary (lines, tests, API)\n```"},
      {"label": "Describe the plan", "description": "I'll explain what I'm planning to change", "markdown": "```\nPlan Description\n────────────────\nYou describe → I visualize:\n\n→ Before/after architecture diagrams\n→ Execution order with dependencies\n→ Risk analysis per component\n→ Decision log (ADR-lite format)\n```"},
      {"label": "GitHub issue", "description": "Pull plan from a specific issue number", "markdown": "```\nGitHub Issue Source\n───────────────────\n$ gh issue view #N\n\n→ Extract requirements from body\n→ Map to file-level changes\n→ Generate execution phases\n→ Link back to issue for tracking\n```"},
      {"label": "Quick file diff only", "description": "Just show the change manifest, skip analysis", "markdown": "```\nQuick File Diff\n───────────────\n[A] src/new-file.ts        +120\n[M] src/existing.ts    +15  -8\n[D] src/old-file.ts        -45\n─────────────────────────────\nNET: +82 lines, 3 files\n\nNo risk analysis or swimlanes\n```"}
    ],
    "multiSelect": false
  }]
)

---

步骤 1：收集数据

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

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

此命令会生成：按操作分类的文件（新增／修改／删除）、行数、受影响的测试文件和依赖项变更。

要从架构层面了解情况，请在受影响的目录上启动一个 Explore Agent：

Agent(
  subagent_type="Explore",
  prompt="Explore the architecture of {affected_directories}. Return: component diagram, key data flows, health scores per module. Use the ascii-visualizer skill for diagrams.",
  model="haiku"
)

---

步骤 2：渲染第 1 级标题（始终执行）

使用 assets/tier1-header.md 模板。加载 Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/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}

[1] Changes  [2] Execution  [3] Risks  [4] Decisions  [5] Impact  [all]

---

步骤 3：询问要展开哪些部分

AskUserQuestion(
  questions=[{
    "question": "Which sections to render?",
    "header": "Sections",
    "options": [
      {"label": "All sections", "description": "Full visualization with all 5 core sections", "markdown": "```\n[1] Change Manifest   [A]/[M]/[D] file tree\n[2] Execution         Swimlane with phases\n[3] Risks             Dashboard + pre-mortems\n[4] Decisions         ADR-lite decision log\n[5] Impact            Lines, tests, API, deps\n```"},
      {"label": "Changes + Execution", "description": "File diff tree and execution swimlane", "markdown": "```\n[1] Change Manifest\n    [M] src/auth.ts         +45 -12\n    [A] src/oauth.ts        +89\n\n[2] Execution Swimlane\n    Phase 1 ====[auth]========▶\n    Phase 2 ----[blocked]--===▶\n```"},
      {"label": "Risks + Decisions", "description": "Risk dashboard and decision log", "markdown": "```\n[3] Risk Dashboard\n    MEDIUM ██░░ migration reversible\n    HIGH   ███░ API breaking change\n    Pre-mortem: \"What if auth fails?\"\n\n[4] Decision Log\n    D1: OAuth2 over JWT (security)\n    D2: Postgres over Redis (durability)\n```"},
      {"label": "Impact only", "description": "Just the numbers: files, lines, tests, API surface", "markdown": "```\n[5] Impact Summary\n    ┌──────────┬─────┬───────┐\n    │ Metric   │Count│ Delta │\n    ├──────────┼─────┼───────┤\n    │ Files    │  12 │  +3   │\n    │ Lines    │ 450 │ +127  │\n    │ Tests    │   8 │  +4   │\n    │ API sfc  │   3 │  +1   │\n    └──────────┴─────┴───────┘\n```"}
    ],
    "multiSelect": false
  }]
)

---

步骤 4：渲染所需部分

按照 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/rules/section-rendering.md 中的约定，渲染每个所需部分。使用相应参考资料中的 ASCII 模式：

部分	参考资料	关键约定
[1] 变更清单	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/change-manifest-patterns.md）	每个文件使用 [A]／[M]／[D] + +N -N
[2] 执行泳道图	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/execution-swimlane-patterns.md）	=== 表示活动，--- 表示阻塞，| 表示依赖
[3] 风险仪表板	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/risk-dashboard-patterns.md）	可逆性时间线 + 3 项事前验尸分析
[4] 决策日志	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/decision-log-patterns.md）	精简版 ADR：上下文／决策／备选方案／权衡
[5] 影响摘要	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/assets/impact-dashboard.md）	表格：新增／修改／删除／净值 + 测试／API／依赖项

---

步骤 5：提供操作选项

渲染完成后，提供后续步骤：

AskUserQuestion(
  questions=[{
    "question": "What next?",
    "header": "Actions",
    "options": [
      {"label": "Write to designs/", "description": "Save as designs/{branch}.md for PR review", "markdown": "```\nSave to File\n────────────\ndesigns/\n  └── feat-billing-redesign.md\n      ├── Header + metadata\n      ├── All rendered sections\n      └── Ready for PR description\n```"},
      {"label": "Generate GitHub issues", "description": "Create issues from execution phases with labels and milestones", "markdown": "```\nGitHub Issues\n─────────────\n#101 [billing] Phase 1: Schema migration\n     labels: component:billing, risk:medium\n#102 [billing] Phase 2: API endpoints\n     labels: component:billing, risk:low\n     blocked-by: #101\n```"},
      {"label": "Drill deeper", "description": "Expand blast radius, cross-layer check, or migration checklist", "markdown": "```\nDeep Dive Options\n─────────────────\n[6] Blast Radius\n    direct → transitive → test impact\n[7] Cross-Layer Consistency\n    Frontend ↔ Backend endpoint gaps\n[8] Migration Checklist\n    Ordered runbook with time estimates\n```"},
      {"label": "Done", "description": "Plan visualization complete"}
    ],
    "multiSelect": false
  }]
)

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

生成 issues： 为每个执行阶段创建一个 GitHub issue，标题为 [{component}] {phase_description}，添加标签（组件 + risk:{level}），设置里程碑，正文内容取自计划各部分，并注明阻塞依赖项。

---

深入分析（第 3 级，按需提供）

用户选择“深入分析”时可用。加载 Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md")，以查看跨层和迁移模式。

部分	展示内容	参考资料
[6] 影响范围	影响的同心环（直接 -> 传递 -> 测试）	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/blast-radius-patterns.md）
[7] 跨层一致性	前端／后端端点对齐情况及差异检测	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md）
[8] 迁移清单	按顺序排列的运行手册，包含顺序／并行区块和时间估算	（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/references/deep-dives.md）

核心原则

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

规则速查

规则	影响	涵盖内容
section-rendering（加载 ${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/rules/section-rendering.md）	HIGH	全部 5 个核心章节的呈现约定
ASCII 图表	MEDIUM	通过 ascii-visualizer 技能实现（框线图、文件树、工作流）

参考资料

按需使用 Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/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	跨层一致性和迁移检查清单

资源文件

按需使用 Read("${CLAUDE_PLUGIN_ROOT}/skills/plan-viz/assets/<file>") 加载：

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

相关技能

• ork:implement - 执行计划的变更
• ork:explore - 了解当前架构
• ork:assess - 评估复杂度和风险