plan-viz

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

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

将计划中的变更渲染为包含风险分析、执行顺序和影响指标的结构化ASCII可视化内容。每个部分都针对评审者的特定问题给出解答。

核心原则： 将判断逻辑融入可视化，而非仅做装饰。

bash

/plan-viz                          # 从当前分支自动检测
/plan-viz billing module redesign  # 描述计划内容
/plan-viz #234                     # 从GitHub议题中提取

STEP 0: Detect or Clarify Plan Context

步骤0：检测或明确计划上下文

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

首先，运行

scripts/detect-plan-context.sh

尝试自动检测：

bash

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

该脚本会输出分支名称、议题编号（如有）、提交次数和文件变更摘要。

如果自动检测到明确的计划（与主分支有提交差异的分支，或参数中包含议题编号），则进入步骤1。

如果上下文模糊，则通过AskUserQuestion进行确认：

python

AskUserQuestion(
  questions=[{
    "question": "我需要可视化什么内容？",
    "header": "来源",
    "options": [
      {"label": "当前分支的变更（推荐）", "description": "自动检测与主分支的git diff差异"},
      {"label": "描述计划内容", "description": "我会说明自己计划进行的变更"},
      {"label": "GitHub议题", "description": "从指定议题编号中提取计划"},
      {"label": "仅快速展示文件差异", "description": "仅显示变更清单，跳过分析环节"}
    ],
    "multiSelect": false
  }]
)

STEP 1: Gather Data

步骤1：收集数据

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.

For architecture-level understanding, spawn an Explore agent on the affected directories:

python

Task(
  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"
)

运行

scripts/analyze-impact.sh

获取精确统计数据：

bash

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

该脚本会生成：按操作类型（新增/修改/删除）分类的文件列表、代码行数统计、受影响的测试文件以及依赖变更情况。

为了理解架构层面的影响，针对受影响的目录启动Explore agent：

python

Task(
  subagent_type="Explore",
  prompt="探索{affected_directories}的架构。返回：组件图、关键数据流、各模块的健康评分。使用ascii-visualizer skill生成图表。",
  model="haiku"
)

STEP 2: Render Tier 1 Header (Always)

步骤2：渲染第一层级头部（必选）

Use

assets/tier1-header.md

template. Fill in from gathered data. This is always shown first.

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]

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

使用

assets/tier1-header.md

模板，填入收集到的数据。这部分内容始终优先展示。

计划：{plan_name} ({issue_ref})  |  {phase_count}个阶段  |  {file_count}个文件  |  +{added} -{removed}行代码
风险等级：{risk_level}  |  置信度：{confidence}  |  可回滚至：{last_safe_phase}
分支：{branch} -> {base_branch}

[1] 变更内容  [2] 执行顺序  [3] 风险情况  [4] 决策记录  [5] 影响分析  [全部]

风险等级 = 所有阶段中的最高风险等级（LOW/MEDIUM/HIGH/CRITICAL）。 置信度 = 若超过50%的变更位于未测试代码中则为LOW，混合情况为MEDIUM，若变更路径测试充分则为HIGH。 可回滚至 = 不可逆操作（删除数据、移除旧列、破坏性API变更等）之前的最后一个阶段。

STEP 3: Ask Which Sections to Expand

步骤3：询问需要展开的章节

python

AskUserQuestion(
  questions=[{
    "question": "Which sections to render?",
    "header": "Sections",
    "options": [
      {"label": "All sections", "description": "Full visualization with all 5 core sections"},
      {"label": "Changes + Execution", "description": "File diff tree and execution swimlane"},
      {"label": "Risks + Decisions", "description": "Risk dashboard and decision log"},
      {"label": "Impact only", "description": "Just the numbers: files, lines, tests, API surface"}
    ],
    "multiSelect": false
  }]
)

python

AskUserQuestion(
  questions=[{
    "question": "需要渲染哪些章节？",
    "header": "章节选项",
    "options": [
      {"label": "所有章节", "description": "完整可视化内容，包含全部5个核心章节"},
      {"label": "变更内容 + 执行顺序", "description": "文件差异树和执行泳道图"},
      {"label": "风险情况 + 决策记录", "description": "风险仪表盘和决策日志"},
      {"label": "仅影响分析", "description": "仅展示数据：文件、代码行、测试、API范围"}
    ],
    "multiSelect": false
  }]
)

STEP 4: Render Requested Sections

步骤4：渲染请求的章节

Section [1]: Change Manifest

章节[1]：变更清单

Use

references/change-manifest-patterns.md

. Render a Terraform-style annotated file tree:

src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── 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

Rules:

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

使用

references/change-manifest-patterns.md

。渲染Terraform风格的带注释文件树：

src/
├── api/
│   ├── routes.py          [M] +45 -12    !! 高流量路径
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** 新文件
├── models/
│   └── invoice.py         [A] +95        ** 新文件
└── tests/
    └── test_billing.py    [A] +120       ** 新文件

图例：[A]新增 [M]修改 [D]删除  !! 风险项  ** 新文件
摘要：+460 -17  |  3个新文件  |  2个修改文件  |  0个删除文件

规则：

使用
```
[A]
```
/
```
[M]
```
/
```
[D]
```
前缀符号（遵循Terraform约定）
显示每个文件的
```
+N -N
```
代码行数统计
用
```
!!
```
标记高风险文件并添加注释
用
```
**
```
标记新文件
始终以摘要行结尾

Section [2]: Execution Swimlane

章节[2]：执行泳道图

Use

references/execution-swimlane-patterns.md

. Show phases as horizontal lanes with dependency lines:

Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+
                                                      |
Tests    ------[Wait]--------[Wait]-----------[E2E Tests]========>

=== Active work   --- Blocked/waiting   | Dependency
Critical path: Schema -> API -> Deploy (estimated: 4-6 hours)

Rules:

```
===
```
for active work,
```
---
```
for blocked/waiting
Vertical
```
|
```
for dependencies with
```
blocks
```
annotations
Identify and label the critical path
Show parallel opportunities explicitly

使用

references/execution-swimlane-patterns.md

。将阶段展示为带依赖线的横向泳道：

后端  ===[Schema]======[API]===========================[部署]====>
                |            |                                ^
                |            +------阻塞------+             |
                |                               |             |
前端 ------[等待]--------[组件]=======[集成测试]=+
                                                      |
测试    ------[等待]--------[等待]-----------[端到端测试]========>

=== 进行中工作   --- 阻塞/等待中   | 依赖关系
关键路径：Schema -> API -> 部署（预计耗时：4-6小时）

规则：

```
===
```
表示进行中工作，
```
---
```
表示阻塞/等待中
垂直
```
|
```
表示依赖关系，并添加“阻塞”注释
识别并标记关键路径
明确展示可并行执行的环节

Section [3]: Risk Dashboard

章节[3]：风险仪表盘

Use

references/risk-dashboard-patterns.md

. Two parts: reversibility timeline + pre-mortem.

Part A: Reversibility Timeline

REVERSIBILITY TIMELINE
Phase 1  [================]  FULLY REVERSIBLE    (add column, nullable)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint, additive)
Phase 3  [============....] PARTIALLY           (backfill data)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop old column)
Phase 5  [================]  FULLY REVERSIBLE    (frontend toggle)

Part B: Pre-Mortem (3 scenarios)

PRE-MORTEM: This plan failed because...

1. {scenario_description}
   Probability: {level} | Impact: {level}
   Mitigation: {action}
   Rollback: {steps} ({time_estimate})

2. ...
3. ...

Rules:

Always identify the point of no return
Generate exactly 3 pre-mortem scenarios (most likely, most severe, most subtle)
Each scenario needs a concrete mitigation, not generic advice

使用

references/risk-dashboard-patterns.md

。包含两部分：可回滚时间线 + 事前分析。

A部分：可回滚时间线

可回滚时间线
阶段1  [================]  完全可回滚    (新增可空列)
阶段2  [================]  完全可回滚    (新增端点，增量式)
阶段3  [============....]  部分可回滚    (回填数据)
              --- 不可逆转点 ---
阶段4  [........????????]  不可逆转        (删除旧列)
阶段5  [================]  完全可回滚    (前端开关)

B部分：事前分析（3种场景）

事前分析：本计划失败的可能原因...

1. {场景描述}
   概率：{等级} | 影响：{等级}
   缓解措施：{行动方案}
   回滚步骤：{步骤}（预计耗时：{时间估算}）

2. ...
3. ...

规则：

必须明确标记不可逆转点
生成恰好3种事前分析场景（最可能、最严重、最隐蔽）
每个场景需包含具体的缓解措施，而非通用建议

Section [4]: Decision Log

章节[4]：决策日志

Use

references/decision-log-patterns.md

. ADR-lite format for each non-obvious choice:

DECISION LOG

#1: {decision_title}
    Context:      {why this decision exists}
    Decision:     {what was chosen}
    Alternatives: {what was rejected and why}
    Tradeoff:     + {gain}  - {cost}

#2: ...

Rules:

Only document non-obvious decisions (skip "we need a database table for invoices")
Always show at least one rejected alternative
Tradeoffs must be honest — show the cost, not just the benefit

使用

references/decision-log-patterns.md

。采用轻量ADR格式记录所有非显而易见的决策：

决策日志

#1: {决策标题}
    背景：      为何做出该决策
    决策：     最终选择的方案
    备选方案：  被否决的方案及原因
    权衡：     + 收益  - 成本

#2: ...

规则：

仅记录非显而易见的决策（跳过“我们需要为发票创建数据库表”这类常规决策）
必须至少展示一个被否决的备选方案
权衡需真实客观——既要展示收益，也要说明成本

Section [5]: Impact Summary

章节[5]：影响分析摘要

Use

assets/impact-dashboard.md

template:

IMPACT SUMMARY
+=========+==========+===========+
| Category | Files   | Lines     |
+=========+==========+===========+
| Added    |    3    |    +395   |
| Modified |    2    |  +65 -17  |
| Deleted  |    0    |      0    |
+---------+----------+-----------+
| NET      |    5    |    +443   |
+---------+----------+-----------+

Tests:    2 new  |  1 modified  |  Coverage: 73% -> 68% (needs +4 tests)
API:      2 new endpoints  |  0 breaking changes
Deps:     +1 (stripe-python)  |  0 removed

使用

assets/impact-dashboard.md

模板：

影响分析摘要
+=========+==========+===========+
| 分类     | 文件数   | 代码行数   |
+=========+==========+===========+
| 新增     |    3    |    +395   |
| 修改     |    2    |  +65 -17  |
| 删除     |    0    |      0    |
+---------+----------+-----------+
| 总计     |    5    |    +443   |
+---------+----------+-----------+

测试：    2个新测试文件  |  1个修改测试文件  |  覆盖率：73% -> 68%（需新增4个测试用例）
API：      2个新端点  |  0个破坏性变更
依赖：     +1（stripe-python）  |  0个移除依赖

STEP 5: Offer Actions

步骤5：提供后续操作选项

After rendering, offer next steps:

python

AskUserQuestion(
  questions=[{
    "question": "What next?",
    "header": "Actions",
    "options": [
      {"label": "Write to designs/", "description": "Save as designs/{branch}.md for PR review"},
      {"label": "Generate GitHub issues", "description": "Create issues from execution phases with labels and milestones"},
      {"label": "Drill deeper", "description": "Expand blast radius, cross-layer check, or migration checklist"},
      {"label": "Done", "description": "Plan visualization complete"}
    ],
    "multiSelect": false
  }]
)

Write to file: Save full report to

designs/{branch-name}.md

using the

assets/plan-report.md

template.

Generate issues: For each execution phase, create a GitHub issue with:

Title:
```
[{component}] {phase_description}
```
Labels: component label +
```
risk:{level}
```
Milestone: current milestone if set
Body: relevant plan sections
Blocked-by references to dependency issues

渲染完成后，提供下一步操作选项：

python

AskUserQuestion(
  questions=[{
    "question": "下一步操作？",
    "header": "操作选项",
    "options": [
      {"label": "写入designs/目录", "description": "保存为designs/{branch}.md用于PR评审"},
      {"label": "生成GitHub议题", "description": "根据执行阶段创建带标签和里程碑的GitHub议题"},
      {"label": "深入分析", "description": "展开影响范围、跨层检查或迁移检查清单"},
      {"label": "完成", "description": "计划可视化已完成"}
    ],
    "multiSelect": false
  }]
)

写入文件： 使用

assets/plan-report.md

模板将完整报告保存至

designs/{branch-name}.md

。

生成议题： 针对每个执行阶段，创建包含以下内容的GitHub议题：

标题：
```
[{组件}] {阶段描述}
```
标签：组件标签 +
```
risk:{level}
```
里程碑：若已设置则使用当前里程碑
正文：相关的计划章节内容
依赖关系：标记“阻塞于”相关依赖议题

DEEP DIVES (Tier 3, on request)

深入分析（第三层级，按需触发）

[6] Blast Radius

[6] 影响范围

Use

references/blast-radius-patterns.md

. Show concentric rings of impact:

                    Ring 3: Tests (8 files)
               +-------------------------------+
               |    Ring 2: Transitive (5)      |
               |   +------------------------+   |
               |   |  Ring 1: Direct (3)     |   |
               |   |   +--------------+      |   |
               |   |   | CHANGED FILE |      |   |
               |   |   +--------------+      |   |
               |   +------------------------+   |
               +-------------------------------+

Direct dependents:   auth.py, routes.py, middleware.py
Transitive:          app.py, config.py, utils.py, cli.py, server.py
Test files:          test_auth.py, test_routes.py, ... (+6 more)

使用

references/blast-radius-patterns.md

。展示影响的同心环：

                    环3：测试文件（8个）
               +-------------------------------+
               |    环2：间接依赖（5个）      |
               |   +------------------------+   |
               |   |  环1：直接依赖（3个）     |   |
               |   |   +--------------+      |   |
               |   |   | 变更文件      |      |   |
               |   |   +--------------+      |   |
               |   +------------------------+   |
               +-------------------------------+

直接依赖：   auth.py, routes.py, middleware.py
间接依赖：          app.py, config.py, utils.py, cli.py, server.py
测试文件：          test_auth.py, test_routes.py, ...（另有6个）

[7] Cross-Layer Consistency

[7] 跨层一致性

Verify frontend/backend alignment:

CROSS-LAYER CONSISTENCY
Backend Endpoint          Frontend Consumer     Status
POST /invoices            createInvoice()       PLANNED
GET  /invoices/:id        useInvoice(id)        PLANNED
GET  /invoices            InvoiceList.tsx        MISSING  !!

验证前端/后端的一致性：

跨层一致性
后端端点          前端消费者     状态
POST /invoices            createInvoice()       已计划
GET  /invoices/:id        useInvoice(id)        已计划
GET  /invoices            InvoiceList.tsx        缺失  !!

[8] Migration Checklist

[8] 迁移检查清单

Generate ordered runbook with constraints:

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]

生成带约束的有序执行手册：

迁移检查清单

串行块A（数据库）：
  1. [ ] 备份生产数据库                    [约5分钟]
  2. [ ] 执行迁移：001_add_invoices.sql           [约30秒]   <- 阻塞#4

并行块B（完成#2后）：
  3. [ ] 部署API v2.1.0                             [约3分钟]
  4. [ ] 更新前端包                        [约2分钟]

串行块C（验证）：
  5. [ ] 冒烟测试                                    [约2分钟]
  6. [ ] 监控错误率15分钟                     [约15分钟]

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
ascii-diagrams	MEDIUM	Box-drawing characters, file trees, progress bars, workflow diagrams
ascii-architecture	MEDIUM	Layered architecture, blast radius, reversibility timelines, comparisons

规则	影响	覆盖范围
ascii-diagrams	中等	方框绘制字符、文件树、进度条、工作流图
ascii-architecture	中等	分层架构、影响范围、可回滚时间线、对比内容

References

参考资料

Change Manifest Patterns
Execution Swimlane Patterns
Risk Dashboard Patterns
Decision Log Patterns
Blast Radius Patterns

变更清单模式
执行泳道图模式
风险仪表盘模式
决策日志模式
影响范围模式

Assets

资源文件

Plan Report Template — Full mustache-style report
Impact Dashboard Template — Impact table
Tier 1 Header Template — 5-line summary

计划报告模板 — 完整的mustache风格报告模板
影响分析仪表盘模板 — 影响分析表格
第一层级头部模板 — 5行摘要模板