plan-flow

Plan Flow

概述

在以下情况下使用此技能：

• 用户需要对代码库中的重复／冗余设计进行完整分析。
• 用户需要包含明确文件级步骤的详细 TODO 计划。
• 用户要求严格提供执行证据：完成一个步骤后进行测试，再更新计划状态。

此技能与具体代码库无关。它定义了分析和规划的方法，而不仅是某个特定代码库中已完成的工作。

核心工作流（分析 -> 规划 -> 执行）

1. 明确范围和约束。

• 确认目标目录／模块以及范围之外的部分。
• 记录兼容性要求、风险容忍度和测试预期。
• 记录基线（git status --short、当前分支、已知阻塞项）。

2. 首先进行结构化冗余分析。

• 梳理架构锚点：
  • 领域模型和架构
  • 工厂／注册表入口
  • HTTP／存储／缓存／日志抽象
  • 路由／服务／提供方适配器
• 根据证据识别重复／冗余候选项：
  • 同一概念存在多个相互冲突的定义
  • 同一职责存在并行实现
  • 已导出但未连接的模块
  • 仍影响可读性的废弃／旧版路径
• 对每项发现，记录：
  • 确切的文件和符号
  • 调用路径或使用证据
  • 修改后的风险
• 参见 references/analysis-playbook.md。

3. 确定优先级，并将分析转化为可执行计划。

• 按影响／工作量／风险／置信度为每项发现评分。
• 将工作分为多个阶段（P0、P1、P2），优先安排风险低、信号强的步骤。
• 根据 references/plan-template.md 创建或更新 plan/<task>.md。
• 严格保持只有一个步骤处于 in_progress 状态。
• 使用以下状态：pending / in_progress / completed / blocked。
• 参见 references/risk-impact-scoring.md。

4. 按严格的「步骤—测试—更新」循环执行。

• 仅实施当前步骤，且只修改列出的文件。
• 立即运行步骤级测试，然后执行项目健康检查。
• 在处理下一步之前，更新计划状态和执行日志。
• 如果失败，记录根本原因，并先完成修复循环再继续。

5. 完成阶段／最终验证。

• 运行阶段检查矩阵和最终回归测试集。
• 报告剩余风险、延期工作和明确的覆盖缺口。

质量关卡

• 每项发现都必须有文件级证据，才能纳入计划。
• 没有测试命令证据的步骤不得标记为 completed。
• 更新计划状态／日志之前，不得开始下一步。
• 如果无法执行完整回归测试，记录确切原因和最接近的替代检查。

参考资料

• references/analysis-playbook.md
  • 如何通过可复现的证据检测重复／冗余设计。
• references/risk-impact-scoring.md
  • 如何确定发现项的优先级、阶段和步骤顺序。
• references/plan-template.md
  • 可复用的计划模板骨架，包含分析表、步骤模板和日志格式。
• references/plan-accomplishments.md
  • 一个已完成的真实示例（仅供参考其风格和细致程度，不是强制范围）。

脚本

• scripts/redundancy_scan.sh <target_dir>
  • 快速初步扫描重复符号名、并行工厂／构建器，以及旧版／死代码线索。
• scripts/findings_to_plan.py --target-dir src --output plan/<name>.md
  • 将扫描结果转换为草拟的执行计划，并进行评分和阶段排序（P0/P1/P2）。
• scripts/plan_lint.py <plan/file.md>
  • 验证计划状态机、测试证据，以及已完成步骤的执行日志完整性。

触发提示

用户提出以下需求时，触发此技能：

• “分析这个库有哪些重复设计／冗余设计”
• “做一个非常完整详细的 todolist／执行计划”
• “每改一处就测试并更新计划状态”
• “按步骤推进并可追踪”

执行规则

• 优先采用小型、可回滚的步骤，而不是大型重构。
• 计划表述应具体到文件路径、符号和命令。
• 避免将分析结论与未经验证的假设混为一谈。
• 如果新证据与先前假设相矛盾，应先修订计划，再编写代码。