用途
squad-refine 用于把积压（backlog）中粗糙的任务描述精化为具体、可执行的需求规格。它通过结构化的用户访谈完成这一过程，输出的是一份独立的 spec 工件，而不是对原描述的改写；用户最初的请求会保留在 description 中，不会被覆盖。
它主要面向 todo 状态的任务。若目标任务不是 todo，会先警告用户并确认后再继续。
主要能力
- 任务读取与状态判断：读取任务标题、描述、优先级、级别、标签与卡片类型。
- 特殊目标处理：
- 若目标是 epic（card_type:'epic'），epic 是容器、不可运行，且自身没有验收标准或计划。此时不运行访谈，而是指向其子任务并停止。
- 若目标是终态（cancelled 或 done），不运行访谈，提示用户先重新打开（reopen，恢复为 todo）再精化，然后停止。
- 说明：被当作阻塞项的 epic 会在所有子任务到达终态后自动完成，其派生的完成汇总仅用于展示，实际存储状态由汇总保持同步。
- 查找既有实现上下文：通过 relationships API 检测依赖（而非从描述文本推断）。若存在依赖，则获取该卡片的实现输出（标题、实现说明、计划），并检查代码库中已确认的文件、接口、schema 等，形成 PRIOR_CONTEXT。若无显式依赖，会先问一个问题：是否有当前任务所基于的先前任务（任务 ID 或 'none'）。
- 缺口分析：从 WHAT、WHY、SCOPE、ACCEPTANCE、CONSTRAINTS、EDGE CASES、DEPENDENCIES 七个维度识别缺失或含糊之处。
- 结构化访谈（GAP-LEDGER LOOP）：这是强制环节。访谈深度来自追问，而非一次性问答。每一轮都重新完整输出缺口台账（ledger），选择价值最高的开放缺口，每次提出 1–4 个问题，记录答案并把对应台账项标记为 RESOLVED。每轮之后对每个新答案做 PROBE-SCAN（探针扫描），要么产出至少一条新的开放缺口，要么明确写出“无新缺口”的理由。停止与否由脚本 refine_ledger.py 判定，退出码为权威结果：0 STOP-CLEAN 可进入综合；1 CONTINUE 表示需要继续更多轮；2 STOP-DEGRADED 表示达到上限且核心缺口仍未解决；3 STOP-ENOUGH 表示用户提前叫停。
- 澄清与研究规则：仅在答案会实质性改变构建内容时才提问，否则前进行并记录假设。偏好/归属/不可逆的范围分叉用菜单形式提问（用户拥有决定权）；可通过分析解决（最佳实践/架构/性能/库）的问题则研究后给出一个带理由的建议，而非菜单。研究按价值触发：设计/架构/高不确定性的卡片才研究，清晰或琐碎卡片不研究。可由环境变量 SQUAD_REFINE_RESEARCH 配置（off | auto-by-value | always，默认 auto-by-value）。
- 综合 spec：构建结构化 spec 对象，包含 goal（1–2 句话）、requirements（完整可测试的字符串数组，使用 REQ/AC/SCOPE(IN)/SCOPE(OUT)/CONSTRAINT/EDGE/SOURCE 软前缀）、qa（每条访谈问题的问答记录）。当外部研究实质性影响卡片时，以 SOURCE: 行给出真实可核验来源；代码库事实引用 file:line 而非 URL。
- 重新评估级别：根据精化后的范围重新评分（L1 琐碎 / L2 单层 / L3 新功能·架构·多层），并在审批环节把级别变更作为显式选择呈现，级别绝不自动应用。
- 审批与保存：以 AskUserQuestion 提供“Approve & save”“Edit more”“Cancel”。批准后通过专用端点写入 spec（不触碰原始 description），写入使用任务 version 作为 CAS 令牌，spec.version 由服务端分配。
使用方式
命令形式为 /squad-refine <ID>，即精化指定 ID 的积压需求。它会先读取 squad 共享上下文（../squad/shared.md）与安全原则（../squad/principles.md），并通过脚本进行“观察门”解析、台账停止门判定与用户引导事件上报。需要本地 Python 3 环境执行相关脚本。
适用场景
适用于 squad 流程中需要把模糊待办任务整理为可执行规格的场景，尤其适合需求边界不清、需要与用户确认范围与验收标准的任务。对于 epic 容器和终态任务则不适用。
限制
- 目标必须是 todo 状态，否则需先确认或重新打开。
- 不覆盖用户原始描述，spec 作为独立工件存在。
- 等级调整不会自动应用，必须在此环节显式选择。
- 停止条件由脚本裁定，不能自行判断“看起来完成了”。
- 研究触发受价值门控与配置项控制，清晰卡片不做研究。
- 若达到上限且 WHAT/SCOPE/ACCEPTANCE 仍开放，会建议 /squad-explore 或拆分卡片，而非输出一个虚假“已精化”的卡片。
暂未提供
关于具体收费、价格、平台支持范围与效果保证，资料未提供。