tikazyq/us-enrich-context

US Enrich Context Skill

Scope: REQUIREMENTS

版本: 0.1.0 | 创建日期: 2025-12-04

---

概述

将符合CRAFT标准的精炼User Story增强为更具场景感和亲和力的版本，通过添加真实业务场景和用户期望，让PM/BA/客户更容易理解需求。

核心价值：

• 保留标准的As-Want-So结构（符合CRAFT标准）
• 新增"业务场景"章节（具体角色、时间、地点、动机）
• 新增"用户期望"章节（非功能性的用户体验期望）
• 100%业务语言，无技术术语

适合人群：不太熟悉敏捷开发但有一定研发背景的用户

---

适用场景

场景1：US太精炼，缺乏场景感

现状：

As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

问题：符合格式但太抽象，PM/客户难以理解具体使用场景

场景2：需要向客户展示需求理解

客户提出需求后，需要快速确认理解是否正确，但标准US太简洁，客户不确定是否准确表达了他们的意图

场景3：团队成员对需求理解不一致

Dev看US觉得清晰，但PM/客户觉得缺乏细节，需要增强场景感帮助所有人达成共识

---

执行步骤

步骤1：读取US基本信息

• 读取US的Front Matter（id, sn, priority等）
• 提取As-Want-So三段内容
• 可选：读取SPEC_PRJ_DESC获取项目背景

步骤2：生成业务场景

基于As部分的角色和So that部分的业务价值，生成真实场景描述：

1. 具体化角色：

   • "用户" → "王小明，某便利店A店的店长"
   • 添加角色的日常工作背景

2. 添加时间地点：

   • "每天早上8点到店后"
   • "在店铺收银台旁边"

3. 描述使用场景和动机：

   • 为什么需要这个功能？
   • 在什么情况下使用？
   • 使用这个功能的目标是什么？

步骤3：生成用户期望

从"So that"推导非功能性期望：

1. 性能期望：

   • 抽象："快速查看" → 具体："3秒内完成登录"

2. 易用性期望：

   • 抽象："方便使用" → 具体："记住账号，不用每次输入"

3. 明确反馈：

   • 抽象："操作成功" → 具体："密码错误时明确提示'密码错误'而非'登录失败'"

步骤4：插入到US文档

保持原有结构不变，在适当位置插入新章节：

## US-ID: 标题

**业务场景**：
[生成的具体场景描述]

**核心需求**：
As a [原始内容]
I want to [原始内容]
So that [原始内容]

**用户期望**：
- [期望1]
- [期望2]
- [期望3]

步骤5：质量验证

• 核心As-Want-So未被修改
• 新增内容100%业务语言（无技术术语）
• 场景描述真实可信（符合项目背景）
• Front Matter和ID完全保留

---

快速开始

最快的3步使用流程：

• [ ] 第1步：准备US文档

  • 文件位置：spec/requirements/user_stories.md（或其他.md文件）
  • 需要包含：As-Want-So 三段式结构
  • 文档示例：至少2-3个US，格式正确但缺乏场景感

• [ ] 第2步：调用SKILL

  • 命令：>>us-enrich 或 >>us-enrich-context
  • AI会自动读取文档并处理（无需手动指定文件路径）
  • 处理过程：为每个US增加"业务场景"和"用户期望"章节

• [ ] 第3步：查看增强后的US

  • 结果位置：原文件（spec/requirements/user_stories.md）
  • 查看方式：打开原文档，查看新增的"业务场景"和"用户期望"章节
  • 或在对话中查看AI的修改摘要

⏱️ 预计耗时：5-10分钟 / 10个US

🆘 遇到问题？ 查看下方"使用说明"章节获取详细指导

---

使用说明

📥 AI会读取什么（输入）

自动读取的文档：

• AI会读取 spec/requirements/ 文件夹下的User Story文档
• 文档需要是 .md格式（如 user_stories.md）
• 每个US需要包含：
  • 文档头部的编号信息（如 id: US-AUTH-001）
  • As-Want-So三段式结构（角色-功能-价值）

项目结构示例：

你的项目/
└── spec/
    └── requirements/
        ├── user_stories.md  ← AI会读取这个文件
        └── acceptance_criteria.md

可选的补充信息（有这些会更好）：

• 如果有项目背景描述文件，AI能生成更贴合项目的场景
• 如果有用户画像文档，AI能使用真实的用户特征

📤 AI会产生什么（输出）

修改的内容： AI会在原有US文件中新增2个章节，原有内容完全保留：

1. 业务场景（新增章节）：

   • 具体的用户名字（如"王小明"）
   • 时间和地点（如"每天早上8点到店后"）
   • 用户的工作背景和使用动机
   • 约100-150字的生动描述

2. 用户期望（新增章节）：

   • 3-5条具体的期望清单
   • 每条都可以被观察或测量（如"3秒内完成登录"）
   • 覆盖性能、易用性、反馈等方面

结果位置：

• 修改后的文档仍在原位置：spec/requirements/user_stories.md
• 原有的As-Want-So内容不会改变
• 你可以在对话窗口中看到AI的修改摘要

示例（修改前后对比）：

# 修改前（精炼版）
## US-AUTH-001: 用户登录

As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

---

# 修改后（丰富版）
## US-AUTH-001: 用户登录

**业务场景**：
王小明是连锁便利店A店的店长，每天早上8点到店后的第一件事就是打开系统查看昨日营收情况。他习惯用自己的手机号+密码登录系统（公司统一配置的账号）。

**核心需求**：
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

**用户期望**：
- 登录过程快速（不超过3秒），因为早上时间紧张
- 系统记住手机号，不用每次都重新输入
- 密码错误时明确提示"密码错误"而非"登录失败"

🎯 如何使用

第1步：确保文档已准备好

• 打开 spec/requirements/ 文件夹
• 确认有User Story文档（.md格式）
• 确认US包含 As-Want-So 结构

第2步：调用这个SKILL

• 在与AI对话时输入：>>us-enrich
• AI会自动读取需求文档并开始处理
• 处理时间：约1-2分钟 / 10个US

第3步：查看结果

• 打开原来的US文档
• 你会看到每个US下面新增了"业务场景"和"用户期望"
• AI会在对话中告诉你具体修改了哪些US

常见问题：

Q: AI会覆盖我原来的US内容吗？ A: 不会。AI只会新增"业务场景"和"用户期望"两个章节，原有的As-Want-So完全保留。

Q: 如果我的US格式不对怎么办？ A: AI会提示你哪些US需要调整，比如："US-AUTH-001缺少As部分，请补充角色信息"。

Q: 我能控制场景丰富到什么程度吗？ A: 可以。在调用时告诉AI你的偏好，比如："请生成简短的场景（50字左右）"或"请生成详细的场景"。

Q: 我不想要某个US的场景可以吗？ A: 可以。在调用时指定："只丰富US-AUTH-001到US-AUTH-005，其他的不用处理"。

---

质量检查

必检项（100%通过）

• [ ] 核心As-Want-So未被修改
• [ ] Front Matter（id, sn等）完全保留
• [ ] 新增内容无技术术语（0个技术词汇）
• [ ] 场景描述真实可信（不脱离项目背景）

建议项（≥80%通过）

• [ ] 业务场景包含具体角色名字
• [ ] 业务场景包含时间和地点信息
• [ ] 用户期望有3条以上
• [ ] 用户期望包含可量化标准（如"3秒内"）
• [ ] 整体可读性提升（比原始US更容易理解）

---

限制条件

✅ 适用场景

• US已经存在，格式基本正确（符合As-Want-So结构）
• US比较精炼，缺乏具体的业务场景描述
• 需要向客户、管理层或非技术人员展示需求理解
• 希望让US更容易被理解，减少后续澄清工作
• 团队成员对需求理解不一致，需要通过场景达成共识

❌ 不适用场景

• 没有任何US文档 → 先使用 interview-to-us 从访谈记录生成US
• US格式完全混乱 → 先使用 user-story-format 验证和修复格式
• US已经很详细，有大量场景描述 → 无需使用本SKILL，避免冗余
• 仅供开发团队内部使用，不对外沟通 → 精炼版即可，无需增强
• US还在起草阶段，内容未定稿 → 等待定稿后再使用

📋 前置条件

• 至少有2-3个完整的User Story（包含As-Want-So三段式）
• US文档是.md格式，位于spec/requirements/目录下
• US已经过基本的格式检查（有id, sn等Front Matter）
• 项目背景信息相对清晰（如果有项目描述文档会更好）

---

特别说明（针对敏捷新手）

为什么需要场景丰富？

精炼版的价值：

• 结构标准，易于管理
• 符合敏捷最佳实践
• 技术团队容易理解

丰富版的价值：

• PM/BA/客户更容易理解
• 帮助团队达成一致理解
• 减少需求澄清的来回沟通

两种风格的适用场景

| 场景 | 推荐风格 | 理由 | |------|----------|------| | Sprint Planning（开发团队内部） | 精炼版 | 团队熟悉敏捷，需要快速浏览 | | 客户需求确认 | 丰富版 | 客户不熟悉敏捷，需要详细场景 | | 需求文档归档 | 精炼版 | 长期维护，保持简洁 | | 需求评审会议 | 丰富版 | 多方参与，需要充分理解 |

学习提示

对比示例：

# 精炼版（符合CRAFT标准）
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

# 丰富版（增强场景感）
**业务场景**：
王小明是连锁便利店A店的店长，每天早上8点到店后的第一件事就是打开系统查看昨日营收情况。他习惯用自己的手机号+密码登录系统（公司统一配置的账号）。

**核心需求**：
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

**用户期望**：
- 登录过程快速（不超过3秒），因为早上时间紧张
- 系统记住手机号，不用每次都重新输入
- 密码错误时明确提示"密码错误"而非"登录失败"

关键改进点：

1. ✅ 具体角色：从"店长"到"王小明，A店店长"
2. ✅ 时间场景：每天早上8点，查看昨日营收
3. ✅ 使用习惯：用手机号登录，公司统一配置
4. ✅ 量化期望：3秒内完成，明确的错误提示

---

>> 命令

>>us-enrich              # 增强单个US的场景感
>>us-enrich-batch        # 批量增强多个US
>>us-enrich-compare      # 对比精炼版和丰富版
>>us-enrich-revert       # 还原为精炼版（移除场景章节）

---

相关 Skills

互补使用：

• us-readability-check - 检查US可读性，发现缺乏场景感的问题后使用本SKILL增强
• interview-to-us - 从访谈记录生成US后，使用本SKILL增加场景感

后续流程：

• user-story-format - 增强后仍需验证As-Want-So格式正确性
• acceptance-criteria - 基于丰富的场景，编写更具体的AC

质量保证：

• principle-invest - 场景丰富不应破坏INVEST原则
• document-quality - 确保增强后的文档质量仍然合格

---

注意：本SKILL是可选工具，不是强制步骤。在WORKFLOW已生成符合标准的US后，根据受众需要选择性使用。