探究工单
在一个问题的时间盒内,充分回答它以便做出决策。交付物是决策记录,而不是合并的代码。
输入
$ARGUMENTS
- Ticket,必需:跟踪器中的编码(例如
ENG-130)或本地ID(例如T-03),该工单类型必须为spike。如果不是探究型工单,则停止并指向/implement-task。 --tasks <file>:本地任务文件。如果未给出,在项目的本地git忽略的RFC文件夹(例如.rfcs/)中查找包含该工单的*.tasks.md文件,然后在docs/rfcs/中查找。--branch <name>:原型的分支名称(如果需要)。否则为<username>/<project-slug>/spike-<task-branch>,遵循与/implement-task相同的命名规则。--unattended:由编排器启动;无人可回答问题。永远不要询问;当需要询问时,停止并在报告中解释。在你自己的工作树中工作。
如果工单已发布,则从跟踪器中读取工单(跟踪器是其内容的真实来源),否则从任务文件中读取。本地RFC和任务文件仅存在于主项目文件夹中:如果你在工作树中,使用 git worktree list(第一个条目)找到它,并通过绝对路径在那里读取它们。永远不要在主文件夹中编辑文件或运行git命令,除非按下面描述的那样编写决策记录。
1. 框定问题
在收集任何内容之前,先写下:
- 问题,用一句话来描述,且该问题有一个答案(例如“Postgres LISTEN/NOTIFY 能在我们的实例规模上处理 2k 事件/秒吗?”,而不是“研究事件处理”)。
- 它解锁的决策,以及依赖它的工单。
- 备选方案,在两者之间做出决策,包括“什么也不做”或最简单的方案(如果它合理)。
- 决策标准,尽可能从RFC的DRIVE部分获取(约束、价值、必要成果),以便根据团队已经认可的重要事项来评判证据。
- 时间盒,来自工单(默认:大约一天的工时)。完成意味着问题已回答或时间盒已用完,以先到者为准。
如果工单过于模糊无法框定问题,则停止并报告 blocked,同时说明需要回答的问题。
2. 收集证据,从成本最低的开始
一旦证据能解决问题就停止;不要为了完整性而持续研究。
- 代码库:现有模式、约束、先前的尝试、相关区域的注释和历史(在相关路径上使用
git log)。 - 主要来源:官方文档、变更日志、发布说明、所涉及库或服务的工单跟踪器。优先选择这些而不是博客文章。如果存在
deep-research技能且问题需要广泛的外部研究,则使用它。 - 测量:当阅读无法解决问题时(性能、兼容性、“这个API真的像那样工作吗?”),构建最小的原型或基准测试来回答问题,在探究分支上,基于最新的main分支。它存在的目的是产生证据:没有超出测量所需的测试,没有打磨,并且永远不合并。推送分支以便证据可重现,但不要打开PR。
跟踪每项证据的来源:已测量(你运行过)、已记录(主要来源这样说)或假设(推断)。引用链接和文件路径。
3. 决定推荐什么
- 使用证据,根据决策标准对每个选项进行评分。
- 推荐一个选项,并包含置信度:高(已测量或记录良好)、中(已记录但未在我们的上下文中测试)、低(主要是推断)。
- 当置信度较低时,优先选择最容易撤销的选项,并说明什么信号会让你改变选择。
- 如果时间盒在问题回答之前已用完,则直说:报告已知内容,并推荐最小的下一步(一个范围更窄的后续探究工单,或者一个可逆的默认选项以便继续推进)。
4. 提议待办变更
决策通常会改变计划。提议,但不应用:
- 要添加的工单,使用与任务文件相同的格式(标题、范围、文件、验收标准、依赖关系),每个1个故事点。
- 要更改的工单(范围、标准或依赖关系)和要删除的工单,每个都附上原因。
- 需要更新的RFC章节。
5. 编写记录并报告
- 使用 templates/decision.md 将决策记录写入主项目文件夹中任务文件旁边的
<rfc-name>.<ticket-id>.decision.md文件中(你在这里编写的唯一文件)。它是一个本地的、未跟踪的文件,就像RFC一样。 - 如果工单已发布,在跟踪器工单上发布简短摘要:问题、推荐和置信度,以及三到五行的关键证据,明确标记为已提议,待批准。
- 如果你直接与用户协作,将工单的状态设置为
decision-proposed(在任务文件中),引导他们查看推荐,并请他们批准、选择另一个选项或延长探究时间。如果处于无人监管模式,将状态留给编排器。 - 以报告结束:
RESULT: decision-proposed | inconclusive | blocked
TICKET: <local id> / <tracker key or "unpublished">
RECORD: <absolute path to the decision record>
RECOMMENDATION: <one line> (confidence: high | medium | low)
PROTOTYPE: <branch or "none">
NOTES: <backlog changes in one line: +N tickets, ~N changed, -N removed; or why blocked>