resolve-blocked

resolve-blocked · 逐项解除开发计划阻塞

目标是让被阻塞的开发计划重新可实施：列出全部阻塞事项；能用证据解除的自己查证，需要拍板的交互确认并附推荐，被依赖项目需修改或补齐契约/证据的通过 CRD 提出 CR。 结论存为独立决策记录，解决方式改进计划正文，按修订后的真实前置重判就绪状态。

调用本技能即授权：写入计划同目录的决策记录，修订计划中与阻塞相关的内容，并为外部依赖创建或续写本地 CRD。代码、PRD、评审报告和实施记录默认只读。用户明确要求仅聊天、只列清单或不改计划时遵循其要求。

references/ 相对本文件解析。仓库规则、技术栈和工具能力在运行时读取，不硬编码目标仓的路径或业务约定。回复语言跟随用户。

边界

• 从零写或重写计划用 dev-plan；评审计划整体质量用 review-dev-plan；落实评审报告的全部意见用 apply-doc-review。本技能只处理阻塞实施的事项；评审报告里的非阻塞问题保留给 apply-doc-review，不顺手改。
• 不实施功能、不跑迁移/部署或有副作用的命令、不写外部系统。CRD 在本地形成可交接的请求，不自动发送、不代改依赖项目，也不把生成 CRD 当作已解除。
• 以 coding agent 协作为前提，用本方可执行动作、依赖项目与交付物描述推进路径，不设置“负责人/待指定”人岗字段，不以“找负责人/交给 QA”代替行动。缺环境、访问权限或实测证据时明确缺口、验证入口与通过判据；真正需要用户授权或取舍的仍交互确认。
• 计划里的陈述是待核实主张。“已核实”“用户已确认”须能在原文、代码或用户原话中找到依据，否则当作未决。
• 若能找到 dev-plan，读取其 SKILL.md 的计划状态与红线部分及 references/plan-skeleton.md，据此判断各类结论落在计划哪一节；复杂架构取舍按需读 references/architecture-quality.md。找不到时按计划自身结构落点。用户自定义模板或历史计划不因章节名不同而强行迁移。

1. 锚定输入与基线

1. 定位计划。未指定且无法唯一确定时询问，不擅自挑一份相邻计划。读取适用的 AGENTS.md/CLAUDE.md 等规则、计划全文、计划关联的 PRD 与关键决策。只读到截断内容时补读后再引用。
2. 计划是阻塞事项的事实源：评审意见通常已经 apply 进计划，不必默认查找评审报告。用户指定了报告时读取；否则只在需要时回读，例如某个阻塞项在计划中缺少来由或证据、顶部 Blocked 的理由在计划里找不到对应项、计划引用了某条评审结论。回读时用计划引用或同目录中「评审对象」指向本计划的报告，优先看其处置节里仍待决的项；多份候选无法确定时询问，不按文件时间猜选。报告中已处置的意见以计划当前内容为准，不重新当作阻塞。
3. 记录基线：计划路径与内容 hash、代码 commit 与 dirty 状态、日期。
4. 读取 references/decisions-contract.md 确定决策记录路径。记录已存在说明不是第一轮，按下节「重复运行同一计划」续做：已确认的决定不重复提问，沿用已有 B-ID 续写。

重复运行同一计划

同一计划可多次运行本技能，直到 Ready。每次运行是一轮，在同一份决策记录续写，不另建文件：

• 先读决策记录的处理轮次与阻塞总览，比较计划当前 hash 与上轮处理后版本。有变化时找出改动段落（用户改稿、评审处置或实施回写），核对已解除项的计划落点是否仍在；被删改或推翻的项重新打开并写明依据。
• 上轮仍阻塞的项逐项核对解除条件是否已满足：CRD 最新答复/交付、账号/配额、spike 或实测结果、用户补充的信息。外部依赖尚无可交接的 CRD 时，按第 3 节补齐，不把旧记录中的人岗分工当作已有请求。满足则按本流程解除；未满足保持仍阻塞，不重复追问用户已明确要等的事项。用户上轮未作答或选择稍后决定的决策项，本轮重新给出上下文再问。
• 计划新增或新暴露的阻塞分配未占用的 B-ID，与遗留项一起列入本轮总览，并标出哪些是新增、重开或遗留。
• 计划、遗留项的解除条件和外部情况都没有变化，且所需 CRD 与下一步行动已齐备时，只回复剩余阻塞及各自的解除条件和行动入口，不改写计划或记录、不新增轮次，也不重复记 SDLC 事件。

2. 收集并分类阻塞

从计划中收集（dev-plan 骨架的常见位置，其他模板找等价内容）：

• 顶部状态为 Blocked 时的定级理由，§11 风险/开放问题中「是否阻塞=是」的行；
• 需求账本中状态为「阻塞」的 NFR-*/A-*，以及值为「未知」但会改变关键决策的数字；
• 事实清单的 [未核实·阻塞] 与契约表的「未核实阻塞」，决策表/ADR 中状态为 Blocked 的项；
• 「实施进度」的当前阻塞及状态为「阻塞」的里程碑；
• 读取了评审报告时，其处置节中仍待决、且计划未体现的阻塞项。

按根因去重，保留所有来源定位。另检查未标注却符合阻塞定义的事项（范围、安全、数据、外部契约或关键 NFR 未决），列为「疑似阻塞」，经用户确认后才纳入。

每项分配 B-01 起的编号，并按解除方式分类：

类型	判据	处理
事实可查	答案在代码、配置、依赖、仓库文档或官方文档中	自行查证，不问用户
需要决策	产品语义、范围/分期、权限与数据归属、外部契约、关键 NFR 数字、难回退的架构取舍、成本	查证后交互确认，附推荐
本方验证/访问前置	本方尚缺实测、spike、环境、账号或访问权限	在只读查证边界内能执行的自行验证；其余明确 agent 可执行动作、缺失前置与通过判据，不越界实施或执行副作用
外部依赖	被依赖项目需修改能力/配置，或补齐其契约、环境与交付证据	实际使用 crd 创建或续写本地 CRD，明确接收项目、请求和验收；仅需用户取舍时提问

查证后类型可能改变：例如查到既有接口不支持分页，原本的事实项就变成“补分页还是改方案”的决策项。

开始逐项处理前，先在聊天里给出阻塞总览：B-ID、事项、来源、阻塞的里程碑/任务、类型、计划处理方式。让用户一眼看清全貌和将要被问哪些问题。

3. 逐项建立上下文

对每一项（依赖链上游的先处理），在开口问之前把下面这些整理清楚：

• 阻塞了什么：受影响的需求、里程碑、任务，以及不解决时最晚在哪一步卡住。
• 为什么阻塞：缺的是哪条证据或哪个决定，计划原文怎么写的（带定位）。
• 已核实事实：亲自读到的代码/配置/文档行为，带 路径:行号。查到的事实若推翻了计划的前提，明确指出。
• 约束：用户原话、PRD、C-*、仓库规则中与此相关的要求。
• 可选方案（需要决策时 2–3 个真正可行且有实质差异的）：做法、对交付/风险/工作量/可回退性的后果，以及它需要计划改动哪些部分。
• 推荐与理由：选哪个，为什么。理由要扎根于本项的证据和约束——例如满足哪条需求、复用哪个已验证范式、哪个更容易回退、哪个把未知留到能验证的时点——而不是泛泛的“更好”。证据不足以支持推荐时直说，并说明还缺什么。

事实可查的项查完即可解除，记下证据；查证无法完成时，按缺口归属转为本方验证/访问前置或外部依赖，不因“未实测”直接要求外部项目改动。

外部依赖：形成可交接的 CR

确认缺口属于被依赖项目后，实际定位并读取可用的 crd/SKILL.md，按提出方流程创建或续写本地 CRD，不只建议用户稍后调用。找不到时查可用安装位置；仍缺失则交付含下列要素的 CR 交接内容，明确“CRD 生成受阻”，不伪造调用或文件，也不擅自安装。

• 先查同主题 CRD，沿用已有 R/Q/RESP 与历史；当前请求、验收和依赖已覆盖时引用，不重复新建。对方返回答复时仍以提出方 crd 整合，不切换为 crd-respond。
• 交接带齐本方与接收项目、阻塞的计划任务、缺口证据、请求的可观察行为/交付物、必要契约与验收条件。本方验证任务单列，不把依赖系统的实现编成本方任务，也不替对方规定内部实施。只有接收项目无法确定且会改变请求对象时才问，不询问人岗分配。
• 已有用户决定直接沿用；涉及新的范围、权限、数据、契约或关键 NFR 取舍时按第 4 节确认，未确认部分标为提议。写文档不代替本方决定或对方接受，不虚构答复、排期或承诺。
• 在决策记录及计划阻塞处链接真实 CRD 与相关条目，记录当前待答/待交付项、解除所需证据和恢复入口。未实际发送就写“文档已保存，未发送”；不增加发送审批步骤，也不自动发送。
• 对方已回复或接受不等于前置已满足。回收答复、交付与本方必要验证证据后，按该阻塞的解除条件核对；只是澄清契约的项可据充分答复解除，要求真实准入/联调的项不能仅凭答复关闭。

4. 交互确认

使用实际可用的交互问答工具（如 AskUserQuestion、request_user_input_async）；没有时在聊天中直接提问并等待。

• 每次提问前，在聊天中先给出这批问题的完整上下文（上一步整理的内容），问题本身也要能独立读懂：写清阻塞的是什么、选项后果。推荐项放在第一位并在标签上注明“推荐”，描述里写推荐理由。允许用户自由回答。
• 互不依赖的项可合并为一次提问（工具单次上限内）；后续选项依赖前一答案的，按顺序问，拿到答案后重新判断下游项的选项。
• 只有用户的明确回答才算确认。“按你推荐的来”是确认，记录为“用户授权按推荐”；默认值、空回答、超时都不算。自由回答含义不清时追问一次。
• 用户选择了非推荐方案时照其执行；若该选择与已核实事实冲突或引入新的阻塞，说明一次后果，记录用户的最终决定。
• 用户中途停止或拒绝回答时，已确认的照常落地，其余保留为未决，不替用户默认决定。

5. 写决策记录

按 references/decisions-contract.md 写入或续写 <计划名>.decisions.md：对象、处理轮次、阻塞总览、逐项记录（上下文、选项、推荐与理由、确认原话/证据、计划落点）、未解除阻塞、就绪结论。续写时追加本轮一行与各项的本轮结论，不改写前几轮的记录。由主 agent 单独写入，写后回读核对。

6. 修订开发计划

把已解除的实质结论写进计划；未解除项仅更新阻塞记录中的解除条件、协作来源与下一步行动。按“事实前提 → 决策/契约 → 设计与任务 → 验证 → 状态”的顺序同步：

• 需求账本：A-* 改为已解除或转写为 C-*/R-*；未知的 NFR 数字填入确认值，来源写“用户 YYYY-MM-DD 确认”或证据路径。
• 事实/契约：[未核实·阻塞] 改为 [已核实·足够] 或 [已核实·缺口]，附证据与最小增量。
• 决策表/ADR：写入选择、必要理由、未选备选和重新评估条件，状态改为 Accepted。
• 受决策影响的接口、失败语义、迁移、§9 验证、里程碑任务与依赖一并修改；新增工作不预填完成，不改已有完成记录。
• §11：已解除的行删除或改为不阻塞；未解除的保留并更新解除条件、下一步动作、CRD 来源（适用时）与最晚确认点，不将待接受的外部契约写成既定事实。
• 「实施进度」的当前阻塞与基线按事实更新；顶部状态按 dev-plan 标准重判：仍有影响范围、安全、数据、外部契约或关键 NFR 的未决项则保持 Blocked，前置都解决才是 Ready。

计划只写最终结论，不写 B-ID、问答经过、“本次处理”这类过程信息，也不提本技能——这些留在决策记录里，否则会随实施过期并误导实施者。改前重读受影响段落，保留用户的并发修改；不改与阻塞无关的章节。

7. 复核与交付

1. 回读计划、决策记录及本轮 CRD：每个已解除项都能在计划中找到落点；搜索被推翻的旧说法，确认没有残留矛盾；需求 → 设计 → 里程碑 → 验收没有因修订断链；状态、§11 与「实施进度」一致。每个外部缺口都有真实 CR 条目或明确生成受阻，本方验证有动作与判据，无人岗等待或越权发送。
2. 计划采用 dev-plan 协议且脚本可用时，运行 check_paths.sh <计划> <仓库根> 与 check_progress.sh <计划> <仓库根>；不适用或缺失时人工核对并说明。
3. 在决策记录的处理轮次中写入本轮计划修订后的 hash 和就绪结论。

最终回复：决策记录、计划与本轮 CRD 的链接（适用时）、本轮已解除/新增或重开/仍阻塞的数量、计划状态变化，以及每个剩余阻塞的下一步动作、所需证据与恢复入口。外部依赖列接收项目、CRD 路径和条目、待答/待交付内容；本方验证列环境/访问前置、执行入口与通过判据。不输出“负责人”分工表。写入失败时说明哪份文件未完成，不声称已保存。

结尾先给一行明确判定：计划修订后的真实状态 Ready 或 Blocked，再给可直接复制的下一步命令：按当前客户端的技能调用写法（如 Codex $resolve-blocked、Claude Code /resolve-blocked），路径填实际文件。

• Ready：/goal 按 <计划路径> 开发。
• Blocked：按缺口给当前可执行的下一步：外部请求给 CRD 交接入口，需修订请求或整合答复时给 crd <实际 CRD 路径>；本方验证给具体动作与前置；用户待决项列明确问题。解除条件满足后再给 resolve-blocked <计划路径> 回收证据、修订计划，直至 Ready。剩余阻塞都在等待且当前无可执行动作时明说：条件满足前重跑不会改变结果。有不依赖阻塞的独立工作时一并列出。

以上为交付后的建议命令，不自行开始实施。

$resolve-blocked goal/LOGIN.md
$resolve-blocked goal/LOGIN.md，参考 goal/LOGIN.review.md，只处理与 M2 相关的阻塞。
$resolve-blocked goal/LOGIN.md，B-03 的供应商答复已到：<答复要点>。

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

登记计划修订后的版本与就绪状态、决策记录路径及已解除/剩余阻塞；不把阻塞解除记成计划已实施。