Community编程与开发github.com

RafaelFerSilva/refinement-agent-skills

通过苏格拉底式提问审查用户故事,直到其准备好进行冲刺规划,并将精炼版本发布到跟踪工具并附带就绪判定。

refinement-agent-skills 是什么?

该技能(称为“精炼用户故事”)通过结构化的苏格拉底式提问,帮助AI代理引导产品负责人完成用户故事的审查。它旨在将通常需要40分钟的讨论压缩为10分钟的确认,确保团队在规划时已有明确的决策记录和可见的空白。技能核心是避免AI暗中补全故事,而是通过提问暴露歧义和未定义之处。支持代码模式(可搜索代码库验证技术事实)和无代码模式(仅限工作区文件)。该过程包括加载和分类用户故事、分类(非用户故事或骨架)、应用需求严格性规则进行静默审计、在提问前通过代理搜索事实、执行多轮结构化检查、根据模板合成精炼故事、给出就绪判定、并路由未决问题。最终输出包含一个警告,强调决策权始终属于产品负责人和团队。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/RafaelFerSilva/refinement-agent-skills/tree/HEAD/skills/refine-story

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

精炼用户故事

通过苏格拉底式提问精炼用户故事:以结构化轮次与产品负责人沟通,直到决策边界为空,然后进行综合。一个高效的会话能将原本40分钟的精炼讨论转化为10分钟的确认,因为团队在规划会议时已经记录了决策并明确了空白。

故事属于产品负责人。你负责审计、提议和提问;每一次编辑都保留原始业务目标,任何需要范围决策的改写都将成为问题,而不是单方面选择。此处发明风险很高:现有的用户故事通常看起来“几乎就绪”,而默默补全它的诱惑很大。一个存在明显空白的用户故事对于精炼来说,远比一个包含产品负责人从未写过的规则、看似“完整”的故事更有价值。

用户故事:$ARGUMENTS

开始之前

阅读工作区中的 docs/agents/refinement.md:它定义了操作模式(带代码或不带代码)、语言(en-US 或 pt-BR,默认为 en-US)、标签和发布路径。如果文件缺失,要求用户运行 /configure-refinement 并停止。所有检查对话、问题和合成的工件都遵循配置的工作区语言。

步骤

  1. 加载。 读取用户故事(文件路径、跟踪器ID或粘贴的文本)、CONTEXT.md、领域架构决策记录,并调用 requirements-rigor 的技能工具。如果此用户故事的 .scratch/<标签>/ 已存在,检查其内容:之前的会话可能已解决了一些问题,你不得重复提问。标签遵循 docs/agents/refinement.md 中的约定。如果 docs/adr/ 或 .scratch/ 不存在,则继续执行,不发出警告。 完成条件:你能够用一行概括该用户故事的分类:可分析(有叙述和一些标准,即使有缺陷)、骨架(仅有标题,或没有标准的叙述)或非用户故事(伪装的功能特性、技术任务、独立的非功能性需求)。

  2. 分类。 非用户故事:说明它实际上是什么类型的工件,提供2到3行理由,并推荐适当的处理方式:伪装的功能特性,使用 /requirements-discovery 分解;技术任务,重新分类为任务;独立的非功能性需求,移至非功能性需求列表。如果该项目存在于工作区中,在标题下方添加 Status: not a US(或 Status: não é US)以及理由以留下线索。在此停止。骨架:继续,第一轮检查要求询问缺失的场景,而不是自己发明它们。 完成条件:分类用一行说明,并且在非用户故事的情况下,也提供了理由和处理方式。

  3. 静默审计。 将 requirements-rigor 的规则应用于叙述和标准:INVEST、Gherkin、反模式(单独阅读 ANTI-PATTERNS.md)、总会触发提问的术语。每个发现都变成一个候选问题或一个保留确切描述行为的修正:将文笔转换为Gherkin,将完成定义移出标准,将实现任务移至备注。 完成条件:每个标准都有一个目标(保留、转换、移动、提问),每个歧义术语都有一个候选问题。

  4. 提问前先搜索事实。 事实是你的责任,永远不是产品负责人的。对于每个候选问题,搜索工作区来源:术语表、.scratch/ 中的先前故事、产品负责人附加的文档。在代码模式下,派遣一个子代理搜索代码库以验证用户故事断言或假设的内容:规则是否存在?限制是否已实现?集成功能是否正常工作?找到的事实成为推荐答案并引用来源。在无代码模式下,搜索仅限于工作区文件,不派遣子代理;如果未找到任何内容,在第1轮顶部用一行说明。 完成条件:每个候选问题都被标记为已由来源回答(附有引用)或对产品负责人开放。

  5. 检查。 调用 socratic-examination 的技能工具并遵循其纪律:轮次、边界、附有引用或“无推荐”的推荐答案、你负责事实而产品负责人负责决策、立即更新术语表。第1轮以一行分类开始,标记阻止判定的问题,并以已移动且无需提问的标准的备注以及已路由给工程团队的问题结束。架构问题不与产品负责人进行轮次:直接路由为对工程团队的开放问题。产品负责人无法回答的问题接收 [TO CONFIRM: whom](或 [A CONFIRMAR: quem])并离开边界。 完成条件:边界为空,或产品负责人请求基于当前信息关闭。

  6. 合成。 按照 TEMPLATE.md 编写精炼后的用户故事,剩余空白处保留可见标记。执行Gherkin自查。给出判定:就绪、需精炼(附上可解锁该故事的问题编号)或受阻(附上理由)。如果存在 [DECOMPOSE],包含分解提案:每个部分的叙述和原始标准的映射。 完成条件:文件存在于 docs/agents/refinement.md 定义的路径,Status: 与判定匹配,并包含最终免责声明。

  7. 路由未决项。 对于会话之外的每个带有 [TO CONFIRM] 的接收者,按照 requirements-rigor 中的 QUESTIONNAIRE.md 编写一份问卷,并将其与精炼后的用户故事一起发布,并在开放问题部分链接该文件。 完成条件:没有未指定接收者或问卷的 [TO CONFIRM] 剩余。

  8. 报告。 简洁地告知用户:判定、用户故事的发布位置、哪些问题可解锁它以及已生成的问卷。

轮次示例

对于用户故事“作为用户,我想导出报告为PDF以便于分享。验收标准1:导出按钮必须正常工作。验收标准2:在后端创建PDF生成服务。验收标准3:PDF必须打开速度快。验收标准4:代码已审查,测试通过。”,在一个无代码工作区中,术语表将运营分析师和客户经理列为报告消费者,第一轮看起来像:

❓ 问题1. 谁导出?(阻止性) 叙述中说的是“用户”。术语表将运营分析师和客户经理列为消费报告的角色。是哪个角色导出,还是两者都导出? 推荐: 运营分析师 [推理:术语表中与“运营报告”关联的角色]。如果没有这个信息,权限将保持未定义,叙述也无法满足INVEST。

❓ 问题2. “打开速度快”是什么意思?(阻止性) 验收标准3不可测试,并且有两种理解:从触发导出到开始下载之间的时间,或文件在阅读器中打开的时间。是哪个意思?最大时间是多少秒? 推荐: 无推荐:源文本没有提供解释的基线或SLA数字。如果没有期望值,记录 [TO CONFIRM: PO] 并继续。

❓ 问题3. 边界情况 来源暗示存在空报告和高容量报告 [推理:报告的数量不同]。哪些对于本次交付是重要的? 推荐: 将两者都包含为场景 [推理:源自源文本]。具体行为由你决定:无推荐。最大容量取决于问题2。

验收标准2和验收标准4不触发问题:验收标准2是一个实现任务,其启用的行为已由验收标准1涵盖,移至备注;验收标准4是团队的定义完成,需从标准中移除。两者都出现在最终工件的审计部分,标记为已移动,而非删除。

最终声明

每个发布的工件都以以下声明结束:

⚠️ 此输出是精炼的准备工作,而非替代品。关于范围、价值和优先级的决策严格属于产品负责人和团队。

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相关技能