Iteration Planning

---
name: ll-iteration-plan
description: 迭代回路 阶段 2/3——需求排序与单轮开发范围决策：读候选池与 tasklist，按固定判据表排序、定单轮范围/会话分工/分支/验收标准，产出可执行的「单轮开发计划」。当用户说"排这轮开发""这轮做什么""定开发计划""哪些先做"，或阶段 1 的候选待排序时使用。
runas: inline
---

# 迭代规划（阶段 2/3）：排序 → 单轮范围 → 技术方向

> **回路位置**：[[ll-iteration-intake]]（阶段 1：初稿）→ **本技能** → [[ll-iteration-parallel-dev]]（阶段 3：执行与发版）。
> **边界**：本技能**只产出计划**（不改代码、不派活、不建 worktree、不动 tasklist 状态）。派活与执行在阶段 3。
> 本技能为**本地技能**：不需要跨会话协作即可运行（区别于阶段 3 的 [[ll-iteration-parallel-dev]]）。

## 0. 输出物

`handoff/<会话名>-单轮开发计划-YYYYMMDD.md`，含七段（见第 6 步模板）：
任务集合 / 本轮不做 / 会话分工 / 分支与基线 / **每条任务的验收标准（可证伪）** / 出包约定 / 决策记录。

> 命名遵循 handoff 规范：`<会话名>-<主题>-<YYYYMMDD>.md`（会话名与日期必填）。

## 1. 收集

- 候选池 `docs/tasklist/16-需求候选池.md`：取「待确认 / 已确认」条目（跳过「证据不足」与「冷置」）
- tasklist：`python scripts/tasklist_db.py sql "SELECT num,status,COALESCE(due_at,'-'),substr(title,1,50) FROM tasks WHERE status='pending'"`（别全文读 md）
- **依赖**：目标任务的正文里若写明「前置」「排在 N 之后」，列出前置链（例：173/174/175 排在 162/166/167 之后）
- **partial 分拣（2026-09-22 按总表四表更正）**：`partial` = **任务没做完、属待办侧**（总表「二、待办 — 部分完成」）→ **可以排进开发 Block**；其中剩余只是「装机验证/观察」的**只读验证并行跑，不占开发产能**。真正进「出包后验证组」的是表三 `done`（代码已交付、装机未闭环，向表四 `verified` 过渡）——**别把状态名用错，旧写法把 partial 当已交付是错的**

## 2. 过滤（不合格的不进排序）

- 证据不足 → 打回阶段 1 补证据
- 与既有 `pending` 任务重复 → 合并，不重复立项
- 已被近期提交/出包修复 → 标「已修待实测」，走实测不走进排序

## 3. 排序（判据按顺序施加，逐条写下理由）

1. **阻塞他人**：是别的任务前置的，优先
2. **影响面**：阻塞日常 > 数据安全/丢失 > 高频摩擦 > 体验改进 > 内部整洁
3. **与既定技术方向冲突度**：冲突大的要么不做、要么先做方向决策（见第 5 步）
4. **工作量与并行度匹配**（2026-09-22 改写：引入 ll-workflow-core Block 模式后，原「单轮 3-5 条」上限作废——批三 17 条、批四 20 条三 Block 实战验证可承载）：会话级并行线数由 Block 编排决定（见 §5.5）；**真正的约束是三个**：①单线内串行深度（一条线堆 >3 个任务就拆线或跨 Block）②Block 数量（>3 个 Block 时考虑拆轮）③**每 Block 活跃会话 ≤6**（2026-09-22 用户放宽，原 ≤4，`ll-iteration-parallel-dev` §5.3，防 429）。单线内 task 写并行仍 ≈1（派遣经济学实测）——即同一条线一次只派一个任务，靠**多线**而非线内并行扩产能。

> 每条排序都要能追溯到第 5 步判据表的某一行或上面 1-4 条——**不许凭空排序**。


## 计划图输出要求（2026-09-23 用户定，实测双渲染支持）

单轮开发计划的**最后必须附一张 SVG 编排图**（Block / 线 / 任务三级可视化，方便用户在对话里直接查看）：

1. **SVG 双处内联输出**（2026-09-23 用户定）：①**对话中**内联 `<svg>...</svg>`（渲染器支持，效果好）②**计划文档**（md）中同样内联 `<svg>...</svg>`（md 渲染器内嵌 HTML/SVG 可视）——两处各**只写一次**，**不要写 `![...](file.svg)` 附件行**（会把源码展开成文本污染画面——2026-09-23 实测）。`.svg` 存档文件可选落盘计划同目录（仅存档，不引用）。
2. **mermaid 图改纵向布局**（`flowchart TD` 或纵向 subgraph）——横向（LR）元素多时字体被压得很小不可读（2026-09-23 实测）；mermaid 可作为补充，SVG 为主交付物。
3. SVG 绘制约定：Block 框（描边分色）> 线框（串行任务合并一框内多行）> 任务行（名称+摘要+规模 S/M/L）；Block 间画「闸门」箭头标注（合并→测试→审计）；底部注功能增量/验收/管理行数对账。

### SVG 模板（计划编排图，弱模型防错）

**模板文件**：`templates/plan-arrangement.svg.tpl`（本技能目录内，独立文件）——**复制该文件全文**改 `{{}}` 占位符 + 按实际 Block/线增删「线框」组即可，勿从零写。填空规则：坐标步长固定（Block 间距 405px 起点 x=30/435/840；线框高 52px/84px/120px 按任务数 1/2/3，间距 10px）；描边分色 #89b4fa/#a6e3a1/#cba6f7；底部对账注必写。**输出姿势（2026-09-23 二次实测修正）**：对话里**必须用附件行** `![图名](相对路径.svg)`（渲染器只认这个；内联 `<svg>` 会被剥成纯文本）；计划文档（md）里同样用附件行引用同文件，或内联 `<svg>`（Obsidian/Typora 支持）二选一。SVG 先落盘计划同目录。

## 4. 确定单轮范围

- 产出「**本轮做**」（条数不设上限，由判据 4 三条约束决定：单线深度 ≤3 + Block ≤3 + 每 Block 活跃会话 ≤6；实测参考批三 17 条 / 批四 20 条）+「**本轮不做**」清单（防蔓延；不做的要写一句为什么，避免下轮重新讨论）
- 标注每条是 `A 级（可独立交付）` 还是 `slice（需多轮）`

## 5. 技术方向决策（逐条对照判据表）

| 判据 | 来源 | 用法 |
|---|---|---|
| **fork 八条铁律** | 记忆「fork 开发八条铁律」 | 破坏性变更留退路 / 新能力默认实验开关 / 先收敛再扩功能 / 启动打包链先搜现成函数 / 权限别用完美锁换效率 / 保住旧 UI / 双通道不自动追版本 / **双方案并存**（上游方案作保底，我们的更优方案作实验特性） |
| **追齐上游的逐项决策偏好** | 记忆「用户在 fork 追齐上游场景的逐项决策偏好」 | 功能型魔改保留、架构型取上游、测试冲突保 fork 语义、预算按实测重定 |
| **并行编排两原则** | 记忆「并行开发会话编排两原则」 | 统一分组（硬要求）；复用优先（偏好行为，用户显式新建则从之） |
| **派遣经济学实测** | 记忆「dispatch economics measured」 | 写并行 ≤3 但有效并行恒 1 ⇒ **同一条线一次只派一个任务**（线内不并行）；**单轮线数不再由本判据限制**，改由 Block 编排 + 判据 4 的三条约束（深度 ≤3 / Block ≤3 / 活跃会话 ≤6）决定；只读调研路径是历史瓶颈 |
| **任务包前置纪律** | tasklist 正文 | 前置未落地不排后置；`partial` 任务只补剩余项，不重复立项 |
| **版本号纪律** | 记忆「构建默认复用 fork 最新版本号」+「包版本号带构建时间戳」 | 计划里写明本轮出包版本号（`1.38.3-YYYYMMDD-HHMM`，**不自增**） |
| **claim-hygiene（断言纪律）** | tasklist 任务 222 + `global-workspace/scripts/claim_check.py` | 计划/交付中的否定性断言（「X 不存在/缺失/未实现」）必须 claim_check 或 `test -f`/`grep -c` 背书；采样查询（head/tail）不得作存在性证据 |
| **上游对照纪律** | memory「issue analysis requires latest upstream release」 | 断言「上游有/没有 X 行为」前先拉上游最新 release 并记录版本依据 |

**方向决策要写结论而非理由堆砌**：每条任务一句"采用 X 方案，因为 Y 判据"。

⚠️ **判据腐烂防线**：若某条判据在本轮**不适用**或与用户当场裁决冲突，写进「决策记录」段并说明 —— 阶段 1 会扫「决策记录」，同类理由出现 ≥2 次即提议把它升格/改写成技能判据（不直接改）。

## 5.5 Block 编排（吸收 ll-workflow-core dev.workflow，2026-09-21 实战）

任务多时按 **Block 模型**编排（原文：`ll-workflow-core/templates/workflows/dev.workflow.yaml`，phase C）：

- **blockPlan**：`blocks: [{id, name, parallel, tasks, estimatedEffort}]` + `dependencyMatrix` + `conflictFiles`
- **并行策略三档（worktree 修订版）**：
  1. 不同文件 → 直接并行
  2. 同文件不同模块 → **可并行**（worktree 隔离），但必须在 conflictFiles 标注**合并冲突预期与合并顺序**
  3. 同文件同段（高冲突对）/隐式依赖 → **同线串行**（实例：preview.go 的 207 先于 200）
- **阶段门（每 Block 末，全过才进下个 Block）**：定向测试全绿（分批 <2min，禁用户活跃时段跑全量）→ integrity 全绿 → 原子提交（显式路径，禁 `git add -A`）→ 按 conflictFiles 标注顺序合并 `main-v2-stable` → **Block 级审计（2026-09-22 用户指令：合并-测试-审计通过才进下个 Block；审计方式见 ll-iteration-parallel-dev §5.6 三原则——审计主会话自行派子对话全量审读）** → tasklist 回写 + `tasklist_db.py gen` → 刷新剩余清单
- **partial 分拣（2026-09-22 更正）**：`partial` = 任务没做完（总表表二「待办 — 部分完成」）→ **可进开发 Block**；其中剩余为只读「装机验证/观察」的**并行跑、不占开发产能**。「出包后验证组」指表三 `done`（代码交付、装机未闭环）→ 表四 `verified`，**不是 partial**
- **并行会话协调**：写领域文件前 `git status`（其他会话可能未提交）；撞号用 `next-task-id.py --release N`；总表三区是 gen 投影**勿手改**
- **断言纪律**：计划文档中的否定性断言（「X 不存在/缺失」）必须 claim_check（任务 222）或谓词背书——计划是断言高发区

## 6. 产出模板（计划文件骨架）

```markdown
# <会话名>-单轮开发计划-YYYYMMDD

## 1. 本轮做（N 条）
| # | 任务 | Block/线 | 会话 | 分支 | 级别 | 验收（可证伪） |
|---|---|---|---|---|---|---|
| 1 | 任务 NNN 一句话 | B1/线A | <会话名或 contact_id> | wt-<主题> | A/slice | <一条可判真假的陈述> |

## 2. 本轮不做（含理由）
- 任务 MMM：<为什么不做>

## 3. Block 编排（对齐 dev.workflow + worktree 修订）
- blocks：[{id, name, parallel, tasks, estimatedEffort}]
- conflictFiles（合并冲突预期 + 合并顺序）：同文件高冲突对同线串行（例：preview.go 先 207 后 200）
- 阶段门（每 Block 末）：定向测试（分批 <2min）→ integrity → 原子提交（显式路径）→ 合并 main-v2-stable → **Block 级审计（不通过不进下 Block）** → tasklist 回写 + gen → 进下 Block
- 出包后验证组：表三 `done`（代码交付、装机未闭环）中差装机验证/观察者不占开发 Block；`partial` 属待办，**可进开发 Block**

## 3-b. Block 级审计安排（每 Block 一节；模板见 parallel-dev/templates/audit-split.md）
| Block | 审计主会话 | 子对话计划（分工原则，由审计主会话自行派） | 全量覆盖要求 |
|---|---|---|---|
| B1 | <审计主会话 contact_id 或「新建」> | <预计 N 个子对话，按域切：…> | 逐任务全量审读+验收锚点逐条核对；汇总回信附覆盖声明 |
| B2 | … | … | … |

> 计划阶段只定「谁审+怎么分」的框架与覆盖要求；实际子对话派发由审计主会话执行（三原则见 ll-iteration-parallel-dev §5.6）。

## 4. 会话分工与基线
- 基线 commit：<sha>（`main-v2-stable` HEAD）
- worktree：`github-repo/worktrees/wt-<主题>`（命名 `wt-<主题>`，无下划线前缀）
- 统一分组：全部会话进同一分组（硬要求）
- 并行会话协调：改领域文件前 git status；撞号 --release

## 5. 依赖与顺序
- <任务 A> 必须先于 <任务 B>：<原因>

## 6. 出包约定
- 版本号：`1.38.3-YYYYMMDD-HHMM`（不自增）｜ 出包时机：<合并后统一出包/分线出包>
- release notes 基线：**上一个「发布的版本」**（发版级增量，覆盖自上次发版全部特性；不是上一时间戳包）

## 7. 决策记录（阶段 1 会回扫本段）
- 决策：<做了什么裁决> ｜ 理由：<一句话> ｜ 是否与既有判据冲突：<是/否 + 说明>
```

## 7. 交给阶段 3

计划里每条任务的**验收标准必须可证伪**（"体感更快" 不合格；"切走再切回 <1s + desktop.log 无秒级空洞" 合格）——阶段 3 的测试验证直接对着它跑。

人工拍板后 → 按 [[ll-iteration-parallel-dev]] 分工派活。

---

## 关联

- [[ll-iteration-intake]]（阶段 1：初稿与消纳）｜ [[ll-iteration-parallel-dev]]（阶段 3：并行开发/发版/验证/回写，**依赖跨会话协作**）
- 方案文档：`docs/自主迭代-执行层缺口分析与落地方案-20260920.md`
- 模板：`templates/block-audit-plan.md`（Block 审计计划骨架，2026-09-22 批三实战提取）