name	us-readability-check
description	检查User Story是否对非技术人员友好，检测技术术语残留、过于精炼的表达、缺乏场景感等问题。适合在US初稿完成后、准备提交验收前使用，当需要质量检查时。帮助敏捷新手自我检查，知道自己写的US哪里需要改进，给出具体可操作的改进建议。
stage	REQUIREMENTS
level_supported	L1-STREAMLINED, L2-BALANCED, L3-RIGOROUS

US Readability Check Skill

Scope: REQUIREMENTS

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

概述

检查User Story的可读性，确保US对PM/BA/客户等非技术人员友好，发现技术术语残留、过于精炼、缺乏场景感等问题，并给出改进建议。

核心价值：

自动检测技术术语残留（目标：0%）
识别过于精炼的表达（建议增加场景描述）
检测缺乏场景感的US（无具体角色、时间、地点）
发现模糊表达（如"用户"太宽泛）
生成可操作的改进建议

适合人群：不太熟悉敏捷开发，想知道自己写的US质量如何的用户

适用场景

场景1：自我检查US质量

写完US后不确定是否符合标准，使用本SKILL进行质量检查，发现问题并改进

场景2：准备客户评审前预检

在发给客户确认前，先检查US是否对客户友好，避免因技术术语或过于精炼而导致客户困惑

场景3：团队代码审查（Peer Review）

团队成员互相审查US时，使用本SKILL作为检查清单，确保质量一致

执行步骤

步骤1：读取US文档

读取requirements/目录下的所有US文件
提取每个US的As-Want-So内容
识别US的ID、SN、标题

步骤2：检测维度（4个核心维度）

检测1：技术术语残留 ⭐ 最高优先级

目标：技术术语密度 = 0%（REQUIREMENTS阶段硬性要求）

关键词库（扩展性设计）：

API/接口类：API, REST, GraphQL, Webhook, Endpoint, 接口, 端点
数据库类：数据库, Database, SQL, NoSQL, Redis, MongoDB, Table, 表
数据格式：JSON, XML, YAML, CSV, Protocol Buffer
认证授权：Token, JWT, OAuth, 会话, Cookie
技术架构：服务端, 客户端, 前端, 后端, 中间件, 微服务
编程术语：函数, 方法, 类, 对象, 变量, 参数, 返回值

检测密度：

✅ 0个术语 = 优秀（符合CRAFT标准）
⚠️ 1-2个术语 = 需要改进（警告）
❌ ≥3个术语 = 不合格（必须修改）

改进建议示例：

"API接口" → "系统功能"
"数据库查询" → "查找信息"
"JSON格式" → "结构化数据"
"Token认证" → "身份验证"

检测2：精炼度检测

目标：As-Want-So每段应≥10字，否则可能过于精炼

检测规则：

As段 < 5字 → ❌ 过于精炼（如"作为用户"）
Want段 < 10字 → ⚠️ 可能过于精炼（如"查看数据"）
So that段 < 10字 → ⚠️ 价值描述不足（如"方便使用"）

建议：

过于精炼的AS：建议具体化角色（如"便利店店长"而非"用户"）
过于精炼的Want：建议增加场景描述（推荐使用 us-enrich-context）
过于精炼的So that：建议补充业务价值（如"节省30%的时间"）

检测3：场景感检测

目标：检测US是否包含具体的场景元素

检测要素：

具体角色名字（如"王小明"、"A店店长"）
时间信息（如"每天早上"、"月底前"）
地点信息（如"在店铺"、"在办公室"）
具体动作描述（如"输入账号密码"而非"登录"）
用户心理/动机（如"因为早上时间紧张"）

评分规则：

≥3项 = ✅ 场景感充足
1-2项 = ⚠️ 场景感一般（建议增强）
0项 = ❌ 缺乏场景感（强烈建议使用 us-enrich-context）

检测4：模糊表达检测

目标：识别过于抽象或宽泛的表达

常见模糊词汇：

角色模糊：
- "用户" → 建议具体化为"店长"、"客户"、"管理员"等
- "系统管理员" → 建议明确是"IT管理员"还是"业务管理员"
功能模糊：
- "查看数据" → 建议具体化为"查看营收数据"、"查看库存数据"
- "管理信息" → 建议具体化为"编辑商品信息"、"删除用户信息"
价值模糊：
- "方便使用" → 建议量化为"节省30%操作时间"
- "提高效率" → 建议具体化为"减少手动输入，避免错误"

步骤3：生成可读性报告

报告格式（按US分组）

# US可读性检查报告

生成时间：2025-12-04
检查范围：requirements/ 目录下所有US
检查US数量：15个

## 总体评分
- ✅ 优秀：8个（53%）
- ⚠️ 需改进：5个（33%）
- ❌ 不合格：2个（14%）

---

## 详细报告

### US-AUTH-001: 用户登录

**总体评分**：⚠️ 需改进（65分）

**问题清单**：
1. ❌ **技术术语残留**（权重：40%）
   - 发现：1个技术术语
   - 位置：Want段 - "输入Token认证"
   - 建议：将"Token认证"改为"身份验证"或"登录凭证"

2. ⚠️ **场景感不足**（权重：30%）
   - 发现：缺少时间、地点、用户心理描述
   - 建议：使用 >>us-enrich 增加场景感

3. ⚠️ **模糊表达**（权重：20%）
   - 发现：As段 - "用户"过于宽泛
   - 建议：具体化为"便利店店长"或"前台收银员"

4. ✅ **精炼度**（权重：10%）
   - 通过：As(8字) Want(15字) So that(12字)

**改进建议**：
- 🎯 高优先级：移除"Token认证"，改为"登录凭证"
- 💡 建议：具体化角色为"便利店店长"
- 💡 可选：使用 >>us-enrich 增加场景感

---

### US-ORDER-003: 下单流程

**总体评分**：✅ 优秀（92分）

**评价**：
- ✅ 无技术术语
- ✅ 场景感充足（包含时间、地点、具体动作）
- ✅ 角色具体（"A店收银员王小红"）
- ✅ 价值清晰且量化（"减少30%录入时间"）

**亮点**：
- 角色具体化做得很好
- 价值量化明确

---

## 改进建议汇总

### 必须修改（阻塞问题）
1. US-AUTH-001: 移除技术术语"Token认证"
2. US-SALES-005: 移除技术术语"JSON数据格式"、"RESTful API"

### 建议改进
3. US-AUTH-001, US-PROD-007: 角色过于宽泛，建议具体化
4. US-SALES-002, US-INV-004: 缺乏场景感，建议使用 >>us-enrich
5. US-ORDER-006: So that价值描述过于抽象，建议量化

### 可选优化
6. 所有US：考虑添加用户心理描述，增强共鸣感

步骤4：推荐后续操作

对于技术术语残留（❌）：必须修改，提供替换建议
对于场景感不足（⚠️）：推荐使用 >>us-enrich 命令
对于模糊表达（⚠️）：给出具体化建议

快速开始

最快的3步使用流程：

第1步：确认已有US文档
- 文件位置：spec/requirements/user_stories.md（或其他.md文件）
- 格式要求：每个US包含 As-Want-So 三段式结构
- 数量建议：至少2-3个US（可以检查更多）
第2步：一键调用检查
- 命令：>>us-readability 或 >>us-readability-batch
- AI会自动扫描 spec/requirements/ 下所有US文档
- 检查过程：4个维度（技术术语/精炼度/场景感/模糊表达）
- ⚠️ 只读检查：不会修改你的US文档
第3步：查看检查报告
- 结果显示：对话窗口中直接显示完整报告
- 报告内容：每个US的评分 + 问题清单 + 改进建议
- 后续操作：根据报告手动修改US，或使用推荐的其他SKILL（如 >>us-enrich）

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

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

使用说明

📥 AI会读取什么（输入）

自动读取的文档：

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

项目结构示例：

你的项目/
└── spec/
    └── requirements/
        ├── user_stories.md      ← AI会读取检查
        ├── acceptance_criteria.md  ← 也会检查AC
        └── nfr.md

AI会检查什么问题：

是否有技术术语残留（如"API"、"数据库"、"JSON"）
US是否太简短（缺少场景描述）
角色是否模糊（如"用户"太宽泛）
价值是否抽象（如"方便使用"不够具体）

📤 AI会产生什么（输出）

生成的内容： AI会生成一份可读性检查报告（新文档），不会修改你的原始US文件

报告内容：

总体评分统计：
- 优秀的US有多少个（✅）
- 需要改进的有多少个（⚠️）
- 不合格的有多少个（❌）
每个US的详细报告（逐个分析）：
- 发现的问题类型（技术术语/过于精炼/缺乏场景/角色模糊）
- 问题具体在哪里（如"Want段使用了'API接口'"）
- 具体的改进建议（如"将'API接口'改为'系统功能'"）
- 评分（0-100分）
改进建议汇总：
- 必须修改的问题（阻塞问题，如技术术语）
- 建议改进的问题（如角色太模糊）
- 可选优化的建议（如增加用户心理描述）

结果位置：

报告会显示在对话窗口中
你可以将报告复制保存为文件
你的原始US文档完全不会被修改

示例（报告片段）：

### US-AUTH-001: 用户登录

**总体评分**：⚠️ 需改进（65分）

**问题清单**：
1. ❌ 技术术语残留
   - 位置：Want段 - "输入Token认证"
   - 建议：将"Token认证"改为"登录凭证"

2. ⚠️ 角色模糊
   - 位置：As段 - "用户"过于宽泛
   - 建议：具体化为"便利店店长"

🎯 如何使用

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

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

第2步：调用这个SKILL

在与AI对话时输入：>>us-readability
AI会自动读取所有US并开始检查
检查时间：约2-5分钟 / 10个US

第3步：查看报告

AI会在对话中显示完整的检查报告
你可以根据报告逐个修改US
对于技术术语问题，必须修改
对于场景感不足，可以使用 >>us-enrich 增强

常见问题：

Q: AI会修改我的US文档吗？ A: 不会。这是一个纯检查工具，只生成报告，不修改原文件。

Q: 如果报告说我的US有技术术语怎么办？ A: 报告会告诉你具体在哪里有什么术语，并给出替换建议。你可以手动修改，或者询问AI具体怎么改。

Q: 我的US很多，检查会很慢吗？ A: 通常10个US检查只需要2-5分钟。如果US很多（超过30个），AI会显示进度。

Q: 检查后发现很多问题，该先改哪些？ A: 报告会按优先级分组："必须修改"（阻塞问题，如技术术语）要立即改，"建议改进"可以逐步改。

质量检查

必检项（100%通过）

不修改原US文档（只读检查）
每个US都生成检查结果
技术术语检测准确率≥95%
报告格式清晰可读

建议项（≥85%通过）

场景感检测准确（识别缺失的场景元素）
模糊表达检测有效（给出具体化建议）
改进建议可操作（不是泛泛的"改进"）
推荐的后续操作合理

限制条件

✅ 适用场景

已有US文档，符合基本的As-Want-So格式
需要质量自查（在提交验收前或客户评审前）
想知道US中哪里需要改进（自我诊断）
准备客户评审前预检，避免因技术术语困扰客户
团队成员互相审查US时，作为标准化检查清单

❌ 不适用场景

完全没有US文档 → 先使用 interview-to-us 从访谈生成US
US格式完全错误（缺少As-Want-So结构） → 先使用 user-story-format 验证和修复格式
需要自动修复US而非只检查 → 本SKILL只生成报告，不修复；需手动改或用其他SKILL
需要检查AC/NFR的详细逻辑 → 本SKILL专注US可读性，不深入检查AC/NFR
期望100%无误报 → 检测基于关键词库，可能有少量误报或漏报

📋 前置条件

至少有2-3个User Story（包含As-Want-So三段式）
US文档是.md格式，位于spec/requirements/目录下
US已经过基本的格式验证（有id, sn等Front Matter）
愿意接受改进建议并手动修改（本SKILL不自动修复）
理解报告中的评分和建议是辅助判断，最终决策由用户做出

分级检查策略

L1-STREAMLINED（快速检查）

检测维度：2个核心维度

技术术语残留（权重70%）
精炼度检测（权重30%）

通过标准：技术术语密度≤10%（≤1个术语/US） 时间目标：< 5分钟 / 10个US

L2-BALANCED（标准检查）

检测维度：3个维度

技术术语残留（权重50%）
场景感检测（权重30%）
精炼度检测（权重20%）

通过标准：综合得分≥75分 时间目标：10-15分钟 / 10个US

L3-RIGOROUS（全面检查）

检测维度：4个全面维度

技术术语残留（权重40%）
场景感检测（权重30%）
模糊表达检测（权重20%）
精炼度检测（权重10%）

通过标准：综合得分≥85分 时间目标：20-30分钟 / 10个US 额外检查：

角色一致性（同一角色在不同US中的描述是否一致）
价值链完整性（所有US的价值是否对齐项目目标）

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

学习指引：每个检测维度的意义

为什么要避免技术术语？

业务语言 vs 技术语言：

# ❌ 技术语言（对客户不友好）
As a 系统管理员
I want to 通过RESTful API获取JSON格式的用户Token
So that 实现OAuth2.0认证流程

# ✅ 业务语言（客户能理解）
As a 系统管理员
I want to 安全地验证用户身份
So that 确保只有授权用户才能访问系统

原因：

PM/BA/客户通常不懂技术术语
技术术语会导致误解（如"Token"可能被理解为"代币"）
需求阶段应聚焦业务价值，不涉及实现细节

为什么需要场景感？

精炼版 vs 丰富版：

# ⚠️ 精炼版（缺乏场景感）
As a 店长
I want to 查看营收
So that 了解业绩

# ✅ 丰富版（有场景感）
As a 便利店A店店长王小明
I want to 每天早上8点到店后立即查看昨日营收数据
So that 快速了解昨日业绩，决定今日备货策略

价值：

帮助团队理解"谁、何时、为什么"使用这个功能
减少误解和来回沟通
让所有人（包括客户）达成一致理解

优秀US示例（供对比学习）

## ✅ 示例1：角色具体、场景清晰、价值量化

As a 连锁便利店区域经理（负责10家门店）
I want to 在每周一早上自动收到上周所有门店的销售对比报表
So that 快速识别表现优异和需要改进的门店，节省2小时的手动统计时间

**评分**：95分
- ✅ 角色具体（区域经理 + 负责范围）
- ✅ 场景清晰（每周一早上 + 自动收到）
- ✅ 价值量化（节省2小时）
- ✅ 无技术术语

## ✅ 示例2：用户心理+具体动作

As a 第一次使用系统的新收银员
I want to 在登录后看到简单的操作指引（不超过3步）
So that 不用等店长培训就能快速上手，减少工作压力

**评分**：92分
- ✅ 角色具体（新收银员）
- ✅ 用户心理（减少工作压力）
- ✅ 量化限制（不超过3步）
- ✅ 场景真实（第一次使用）

>> 命令

>>us-readability               # 检查单个US可读性
>>us-readability-batch         # 批量检查所有US
>>us-readability-report        # 生成完整可读性报告
>>us-tech-terms               # 只检查技术术语（快速模式）
>>us-recommend-fix            # 推荐自动修复建议

Install Skill

SKILL.md