linear-refine

Linear Refine

将仓库根目录用作工作流来源。阅读并遵循：

• agents/questioner.md
• docs/questioner.md
• docs/agent-required-passes.md
• docs/superpowers-linear-persistence.md
• templates/linear-plan-comment.md
• schemas/linear-ai.plan.v1.schema.yaml

一次只问一个问题。在将计划标记为就绪之前，先运行必需的本地审查／推演环节。

Claim Lock

遵循 docs/workflow.md 中的 Claim Lock Rule。开始时，重新读取 issue；如果它已带有 in-use，且本次运行并非在恢复自己先前的认领，则停止并报告该 issue 已被认领，不做任何更改。否则，在认领 issue 时添加 in-use 标签。当本次运行停止处理该 issue 时，移除 in-use：在就绪交接、受阻或放弃时都要移除。in-use 不属于 llm-* 命名空间，因此必须显式释放。

认领时，还要将 linear-ai:claim 区块写入 issue 描述（templates/linear-claim-block.md），并填写 claimed_by: linear-refine 和 ISO 8601 格式的 claimed_at，同时保留描述中的其他内容。释放时，移除认领区块。

Questionnaire Start

在编写就绪计划之前，根据源证据判断是否需要问卷。源证据包括 issue、评论、关联文档和代码库检查。如果不存在实质性歧义，记录无需问卷，并继续编写就绪计划。

实质性歧义 = 任何产品行为、UX、范围或数据语义可能在多个合理选项之间有所不同的分支。存在多个合理选项的设计选择始终属于实质性歧义，即使代码证据更支持其中一个选项也是如此——提供证据并给出推荐答案，而不是自行决定。只有纯机械性的选择（命名、文件位置、复用完全相同的现有模式）才可以不提问而自行决定；在 do_not_assume 中记录被排除的替代方案。

如果穷尽源证据后仍存在实质性歧义，则启动真正的问卷／访谈流程，而不是依赖复制粘贴的推演内容。如果可用，使用 grill-me 或 grill-with-docs，但不要要求必须安装这些技能。如果这些技能不可用，则直接执行备用流程：提出一个具体问题，附上推荐答案，等待用户回复，然后更新计划草稿再提出下一个问题。

只有当问卷证据表明每个实质性歧义都已得到解答，或已明确接受为未知时，才可将 plan_status: ready 标记为就绪。

Subagent Relay Mode

作为批处理子 Agent 运行且无法直接联系人的情况下，不得免除访谈要求。将每轮问题发送给负责调度的协调 Agent，并等待转达的答案；暂停期间保留 in-use 认领。在存在尚未得到回答且未被操作员明确接受的实质性问题时，绝不能将 plan_status: ready 设为就绪。

Non-Technical Intake Handoff

如果 issue 带有 nontechnical-intake，则将其视为需要先进行技术转译的通俗语言需求。

编写就绪计划之前：

• 保留原始的通俗语言报告。
• 阅读 Technical triage gaps 部分。
• 根据 issue、评论、关联文档、Linear 上下文和仓库证据，识别受影响的系统。
• 将期望的成功结果转化为可测试的验收标准。
• 使用技术发现替换或补全 Technical triage gaps。
• 无法根据现有证据解决的未知项必须明确保留。
• 只有当剩余未知项已解决或被明确接受时，才可将 plan_status: ready 标记为就绪。

技术分诊完成后，使用 save_issue 移除 nontechnical-intake，并应用常规的细化标签转换。如果无法写入 Linear，则在 REQUIRED_LINEAR_MUTATIONS 中列出移除 nontechnical-intake 的操作。

方案细化

围绕计划中的每个重要分支，持续深入地询问用户，直至双方达成共识。一次只处理一个决策，理清各决策之间的依赖关系，并为每个问题提供建议答案。

一次只问一个问题。如果可以通过查看 issue、评论、关联文档或代码库来回答问题，就先查看这些来源，而不是提问。

用户每次回答后，重述已确认的决策；如有条件，则更新计划草稿或 Linear 评论，并询问该分支是否还有其他内容需要补充。如果有，就在当前步骤继续提出下一个聚焦问题。如果没有，且该分支已解决，就转到下一个分支，或建议进入下一个工作流步骤。

只有在所有重要分支都完成细化，或用户明确接受剩余未知事项后，才将 plan_status: ready 标记为就绪。

Linear MCP 约定

如有以下 Linear MCP 工具，请使用：

• get_issue - 读取当前 issue 字段、标签、状态和分支元数据。
• list_comments - 创建新版本前，读取现有的带标记计划／状态评论。
• save_comment - 发布带标记的计划评论，或回复相关讨论串。
• save_issue - 应用 llm-ready，移除其他 llm-* 标签；开始时添加 in-use 声明，停止时移除；并在可写入时更新状态。

使用以下内容验证带标记的计划评论：

scripts/validate_marked_comments.ts <plan-comment-file>

如果有 Linear 元数据快照，请使用以下内容验证标签：

scripts/validate_marked_comments.ts --metadata <metadata.json> <plan-comment-file>

使用 Agent 可用的本地 JavaScript 包管理器或运行时：Bun 可直接运行 .ts 脚本；Node/npm/pnpm/yarn 环境应通过 tsx 等 TypeScript 运行器运行这些脚本。

如果 Linear MCP 写入工具不可用，不要声称标签、状态或评论已更新。输出 REQUIRED_LINEAR_MUTATIONS，其中包含准确的评论正文以及标签／状态变更。

步骤完成交接

细化完成草稿、受阻或就绪的计划版本后，报告变更内容、验证／写入依据、当前 Linear 标签／状态以及建议的下一步。

询问用户在本次细化步骤中是否还有其他内容需要补充。如果有，就继续当前步骤并更新计划。如果没有，就建议进入下一个工作流步骤；通常在存在 llm-ready 时进入 linear-implement，如仍有歧义，则进入其他方案细化分支。

用户回答“不”后，询问是否要继续执行建议的下一个技能。明确说出建议的技能名称，并等待用户确认；不要自动运行。

使用以下回复格式：

• 当前阶段
• 变更内容
• 依据
• 缺少的依据
• 未解决的阻碍
• 建议的下一步
• 建议的下一个技能
• 问题：进入下一步前，还有其他内容需要补充吗？
• 问题：你想继续使用建议的下一个技能吗？

最新的带标记计划评论为 plan_status: ready、标签／状态变更已应用或已输出，且没有尚未接受的阻碍性问题时，停止。