# Spec Checklist

> Use when 需要在当前 Spec Pack 中检查文档是否存在待澄清/待确认/TBD/TODO 等高价值不确定点，并用“一次只问一个问题→立刻回写文档→必要时回到扫描”的循环把不确定性收敛。

- Skill: `zixun-github/spec-checklist` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zixun-github/spec-checklist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zixun-github/spec-checklist/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: zixun-github (https://skillmd.com/u/zixun-github)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zixun-github/spec-checklist

---


# spec-checklist（Spec Pack 文档待澄清点扫描与收敛）

## 概述

本技能用于在**当前 Spec Pack** 内按流程顺序扫描文档，找出“待澄清/待确认”的**高价值问题**，并通过**一次只问一个问题**的循环把结论回写到对应文档，直到不确定性被消除或被转成可验证条目。

**核心原则：不猜、不批量问、不留口头结论；每次裁决后立刻落盘。**

## 何时使用

- 你看到 spec pack 文档中出现 `待确认/待澄清/TBD/TODO/未定/暂定/Open Questions/???/FIXME` 等
- 你不确定某段文本是“结论”还是“占位符/假设/口头约定”
- 你需要把不确定性收敛为：**已确认结论** 或 **可执行验证项**

## 硬规则（必须遵守）

- **门禁优先**：只要要读写 `{FEATURE_DIR}/requirements|design|implementation|verification`，必须先执行 **REQUIRED SUB-SKILL：`spec-context`** 获取上下文，并在对话中回显 `FEATURE_DIR=...`（允许 `(reuse)`）。
- **spec-context 失败就停止**：若无法得到有效 `FEATURE_DIR=...`，必须立刻停止；只输出“阻断原因 + 需要的最小输入”（例如：切到正确 spec 分支、或提供实际存在且含 `requirements/` 的 `FEATURE_DIR`）。
- **禁止猜测/默认值冒充结论**：看到 TBD/待确认时，除非用户已明确裁决，否则不得把它“补全成合理默认值”并写入文档。
- **一次只问一个问题**：每轮只提出 **1 个最高杠杆澄清问题**（2–4 个选项 + 推荐项 + 兜底“其他/不确定”）。
- **问完就回写**：用户回答后，必须**立刻更新对应文档**（消除占位符），并在需要时联动更新相关文档（例如 AC、范围、数据口径、接口契约、测试计划等）。
- **回写后必须提交（受 AUTO_COMMIT 控制）**：每次完成"用户回答 → 回写文档/联动更新"后：
  - `AUTO_COMMIT=true`（默认）：必须在本轮结束前做一次 git 提交，确保每轮澄清都有可追溯的提交点（提交信息必须使用中文）。
  - `AUTO_COMMIT=false`：跳过 `git add` + `git commit`，改为输出"已变更文件清单，请手动提交"并列出本轮修改的文件路径。
- **给定文件 ≠ 跳过门禁**：如果用户给了文档路径，你可以跳过“全量扫描”，但只要该文件位于/可能位于 `{FEATURE_DIR}` 下，仍必须先 `spec-context` 再读写。

## 选点顺序（先按 spec-pack 流程，从源头到下游）

**第一优先级永远是“文档流程顺序”。**因为前置文档的裁决会连锁影响后置文档，所以必须从源头开始调整：

1. 先处理最靠前文档的未决点（例如先 `requirements/raw.md`，再 `solution.md`，再 `prd.md` …）
2. 只有当“前置文档的未决点清零 / 或已转成明确的验证项”后，才允许进入后置文档的澄清与回写

在**同一份文档内部**，才使用“高价值”规则决定先问哪一条：
- **阻断实现/验收**：范围边界、入口流程、业务规则、AC、关键数据口径、权限模型
- **影响面大且不可逆**：对外/跨模块契约、数据迁移/回滚、合规安全、删除策略
- **风险与成本**：性能/容量/可靠性目标、灰度/发布/回滚策略、依赖与 SLA
- **可延期**：文案、视觉细节、非关键配置（除非影响验收）

## 流程（按你给的步骤固化）

### 步骤 0：是否给定文件？

- “给定文件”仅指：用户提供了**可定位的文档路径**（例如 `{FEATURE_DIR}/requirements/solution.md`）。仅给片段/截图/口头描述不算给定文件。
- 若用户**给定了文件路径**：记录为 `TARGET_DOC`，直接进入 **步骤 2**（但仍需满足上面的门禁规则）。
- 若**未给定文件**：正在执行 `spec-context` 获取上下文，并回显 `FEATURE_DIR=...`，然后进入 **步骤 1**。

### 步骤 1：按 Spec Pack 流程顺序扫描（只扫描存在的文档）

按顺序扫描并提取“待澄清/待确认”的候选点：
- `requirements/raw.md`
- `requirements/solution.md`
- `requirements/prd.md`
- `requirements/prototype.md`
- `design/research.md`
- `design/design.md`
- `implementation/plan.md`
- `verification/test-plan.md`
- `verification/usecase.md`
- `verification/suites.md`
- `verification/report-*.md`

扫描方法（合并去重）：
- **关键词信号**：`待确认|待澄清|TBD|TODO|TBC|未定|暂定|暂不确定|后续再定|后续再议|Open Questions|FIXME|\?\?\?`
- **结构缺口信号**：缺少范围边界/角色权限/数据口径/异常策略/验收口径/发布回滚/契约细节

输出一个列表（对话内维护即可）：
- **候选澄清点**：按**文档流程顺序**分组与排列；每条包含「文件→章节→原文片段→为什么高价值（阻断/不可逆/风险）」；同一文件组内再按高价值排序

### 步骤 2：最小澄清循环（一次只问一个问题）

重复以下闭环：
1. 从“候选澄清点”中选择 **1 条最高优先级**（先取**最靠前文档**的未决点；再在该文档内选最高价值）
2. 把它改写成 **1 个可裁决问题**（2–4 个选项 + 推荐项 + 兜底）
3. 等用户回答
4. **立刻回写文档**：把该点从“占位符/未定”改为“结论/规则/验收口径”，并同步更新受影响的其它文档段落
5. **立刻 git 提交（受 AUTO_COMMIT 控制）**：
   - `AUTO_COMMIT=true`（默认）：只提交本轮澄清导致的相关文档变更；避免提交敏感文件（如 `.env`、凭据）。若没有实际文件变更则跳过提交。
   - `AUTO_COMMIT=false`：跳过提交，输出"以下文件已变更，请手动提交："并列出本轮修改的文件路径。
6. 从候选清单移除已解决项；若回写引入新不确定点，则加入候选清单

> 用户施压“别问了/一次问完/直接给默认值”时：仍然只问 1 个最高杠杆问题；其余未决项必须留在文档里，并转换为可执行验证项（而不是口头记账）。

### 步骤 3：回跳规则

- 若未给定文件：每解决 1–3 个问题后，回到 **步骤 1** 继续扫描（因为回写可能暴露新的缺口）。
- 若给定了文件：只在该文件及其直接相关文档范围内循环；当不确定点清零则结束。

## 回写最小格式（避免“口头结论”）

当你在文档中消除一个“待确认/TBD”点时，至少要把该处改成以下之一：
- **已裁决结论**：明确写出规则/口径/权限/范围/AC（避免“暂定/后续再议”）
- **验证项（仍不确定时）**：把它变成可执行验证条目（含：假设/风险 → 方法 → 成功/失败信号 → 触发动作），并明确“在进入实现/验收前必须完成”

并在必要时补 1 行“联动更新”提示：指出哪些章节/文档因为该裁决需要同步更新（例如 `implementation/plan.md` 的任务与验证步骤、`verification/usecase.md` 的用例与数据口径）。

## Git 提交最小步骤（每轮澄清后执行一次，受 AUTO_COMMIT 控制）

**当 `AUTO_COMMIT=true`（默认）时：**

- **检查变更**：`git status`；`git diff`
- **暂存相关文件**：`git add <本轮修改的文档路径...>`
- **提交（中文信息）**：提交信息建议包含"澄清点 + 影响文档"，例如：
  - `澄清：权限模型与数据口径`
  - `澄清：验收口径（更新 usecase 与 test-plan）`
- **确认干净**：`git status`

**当 `AUTO_COMMIT=false` 时：**

- 跳过 `git add` + `git commit`
- 输出"以下文件已变更，请手动提交："并列出本轮修改的文件路径
- 继续进入下一轮澄清循环（不因跳过提交而中断流程）

## 快速参考

| 你看到的信号 | 你必须做什么 | 你绝不能做什么 |
|---|---|---|
| “TBD/待确认/未定” | 生成 1 个可裁决问题并只问这一题 | 直接补默认值当成结论写回 |
| 用户要你“一次问完” | 只问最高杠杆 1 题，其余转验证项 | 抛 20 个问题清单让用户疲劳回答 |
| 用户给了文件路径 | 直接聚焦该文档进入步骤 2 | 因为“有路径”就跳过门禁读写 |

## 红旗（出现任意一条 = 立刻停止并纠正）

- 未回显 `FEATURE_DIR=...` 就开始读写 spec pack 文档
- 把“合理默认值”当“已确认结论”写进文档
- 前置文档未收敛就跳到后置文档修改/澄清（违反“从源头到下游”的顺序）
- 一次问多个问题/一次给用户多个裁决点
- 用户已回答但你没有立刻回写文档（只在对话里总结）

## 常见借口与反制（来自压测的典型失败）

| 借口（压力来源） | 常见违规行为 | 必须的反制动作 |
|---|---|---|
| “不要问我问题，直接给结果” | 直接把 TBD 补全成默认值写回 | 明确：需要裁决；只问 1 个最高杠杆问题并回写结论 |
| “一次性把问题都列出来” | 输出长清单、失去优先级与闭环 | 只问 1 题；其余留在文档并转为验证项/待办（可追溯） |