name	us-enrich-context
description	为精炼的User Story增加真实场景描述、用户心理和具体对话，让US对PM/客户更亲切易懂。适合在US初稿完成后、需要向客户展示理解或准备验收时使用，当US格式正确但缺乏场景感时。帮助不熟悉敏捷的PM/BA、需要对外沟通的团队，通过丰富的场景感让需求文档更容易被理解和接受。
stage	REQUIREMENTS
level_supported	L1-STREAMLINED, L2-BALANCED, L3-RIGOROUS

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部分的业务价值，生成真实场景描述：

具体化角色：
- "用户" → "王小明，某便利店A店的店长"
- 添加角色的日常工作背景
添加时间地点：
- "每天早上8点到店后"
- "在店铺收银台旁边"
描述使用场景和动机：
- 为什么需要这个功能？
- 在什么情况下使用？
- 使用这个功能的目标是什么？

步骤3：生成用户期望

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

性能期望：
- 抽象："快速查看" → 具体："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个章节，原有内容完全保留：

业务场景（新增章节）：
- 具体的用户名字（如"王小明"）
- 时间和地点（如"每天早上8点到店后"）
- 用户的工作背景和使用动机
- 约100-150字的生动描述
用户期望（新增章节）：
- 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秒），因为早上时间紧张
- 系统记住手机号，不用每次都重新输入
- 密码错误时明确提示"密码错误"而非"登录失败"

关键改进点：

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

>> 命令

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

us-enrich-context

Install Skill

SKILL.md