myclaude/.claude/skills/requirements-clarity/SKILL.md

name, description, activation_triggers, tools

name	description	activation_triggers	tools
requirements-clarity	Automatically detect vague requirements and transform them into crystal-clear Product Requirements Documents (PRDs) through systematic clarification	User describes a feature without technical details Request lacks acceptance criteria or success metrics Scope is ambiguous (e.g., "add authentication", "implement user management") Missing technology stack or implementation constraints No edge cases or error handling mentioned Vague action verbs without specifics ("add", "create", "improve", "fix")	Read, Write, Glob, Grep, TodoWrite

Requirements Clarity Skill

When to Activate

This skill should automatically activate when Claude detects:

1. Vague Feature Requests

   • User says: "add login feature", "implement payment", "create dashboard"
   • Missing: How, with what technology, what constraints?

2. Missing Technical Context

   • No technology stack mentioned
   • No integration points identified
   • No performance/security constraints

3. Incomplete Specifications

   • No acceptance criteria
   • No success metrics
   • No edge cases considered
   • No error handling mentioned

4. Ambiguous Scope

   • Unclear boundaries ("user management" - what exactly?)
   • No distinction between MVP and future enhancements
   • Missing "what's NOT included"

Skill Behavior

Upon activation, this skill transforms vague requirements into actionable PRDs through systematic clarification.

Core Principles

1. Systematic Questioning

   • Ask focused, specific questions
   • One category at a time (2-3 questions per round)
   • Build on previous answers
   • Avoid overwhelming users

2. Quality-Driven Iteration

   • Continuously assess clarity score (0-100)
   • Identify gaps systematically
   • Iterate until ≥ 90 points
   • Document all clarification rounds

3. Actionable Output

   • Generate concrete specifications
   • Include measurable acceptance criteria
   • Provide executable phases
   • Enable direct implementation

---

Clarification Process

Step 1: Initial Requirement Analysis

Input: User's requirement description

Tasks:

1. Parse and understand core requirement
2. Generate feature name (kebab-case format)
3. Create output directory: ./.claude/specs/{feature_name}/
4. Perform initial clarity assessment (0-100)

Assessment Rubric:

功能清晰度 (Functional Clarity): /30 points
- Clear inputs/outputs: 10 pts
- User interaction defined: 10 pts
- Success criteria stated: 10 pts

技术具体性 (Technical Specificity): /25 points
- Technology stack mentioned: 8 pts
- Integration points identified: 8 pts
- Constraints specified: 9 pts

实现完整性 (Implementation Completeness): /25 points
- Edge cases considered: 8 pts
- Error handling mentioned: 9 pts
- Data validation specified: 8 pts

业务背景 (Business Context): /20 points
- Problem statement clear: 7 pts
- Target users identified: 7 pts
- Success metrics defined: 6 pts

Initial Response Format:

我已经理解您的需求。让我帮您完善这个需求规格。

**当前清晰度评分**: X/100

**已明确的部分**:
- [List what's clear]

**需要澄清的部分**:
- [List gaps]

让我开始系统性地澄清这些内容...

Step 2: Gap Analysis

Identify missing information across four dimensions:

1. 功能范围 (Functional Scope)

• What is the core functionality?
• What are the boundaries?
• What is out of scope?
• What are edge cases?

2. 用户交互 (User Interaction)

• How do users interact?
• What are the inputs?
• What are the outputs?
• What are success/failure scenarios?

3. 技术约束 (Technical Constraints)

• Performance requirements?
• Compatibility requirements?
• Security considerations?
• Scalability needs?

4. 业务价值 (Business Value)

• What problem does this solve?
• Who are the target users?
• What are success metrics?
• What is the priority?

Step 3: Interactive Clarification

Question Strategy:

1. Start with highest-impact gaps
2. Ask 2-3 questions per round
3. Build context progressively
4. Use user's language
5. Provide examples when helpful

Question Format:

我需要澄清以下几点以完善需求文档:

1. **[Category]**: [Specific question]?
   - 例如: [Example if helpful]

2. **[Category]**: [Specific question]?

3. **[Category]**: [Specific question]?

请提供您的答案,我会基于此继续完善 PRD。

After Each User Response:

1. Update clarity score
2. Document new information in clarification log
3. Identify remaining gaps
4. If score < 90: Continue with next round of questions
5. If score ≥ 90: Proceed to PRD generation

Score Update Format:

感谢您的补充! 

**清晰度评分更新**: X/100 → Y/100

**新增明确的内容**:
- [Summarize new information]

**剩余需要澄清的点**:
- [List remaining gaps if score < 90]

[If score < 90: Continue with next round of questions]
[If score ≥ 90: "完美! 我现在将生成完整的 PRD 文档..."]

Step 4: PRD Generation

Once clarity score ≥ 90, generate comprehensive PRD.

Output Files:

1. Clarification Log: ./.claude/specs/{feature_name}/clarification-log.md
2. Final PRD: ./.claude/specs/{feature_name}/prd.md

---

PRD Document Structure

# {Feature Name} - 产品需求文档 (PRD)

## 需求描述 (Requirements Description)

### 背景 (Background)
- **业务问题**: [描述要解决的业务问题]
- **目标用户**: [目标用户群体]
- **价值主张**: [此功能带来的价值]

### 功能概述 (Feature Overview)
- **核心功能**: [主要功能点列表]
- **功能边界**: [明确包含和不包含的内容]
- **用户场景**: [典型使用场景描述]

### 详细需求 (Detailed Requirements)
- **输入/输出**: [具体的输入输出规格]
- **用户交互**: [用户操作流程]
- **数据要求**: [数据结构和验证规则]
- **边界条件**: [边界情况处理]

## 设计决策 (Design Decisions)

### 技术方案 (Technical Approach)
- **架构选择**: [技术架构决策及理由]
- **关键组件**: [主要技术组件列表]
- **数据存储**: [数据模型和存储方案]
- **接口设计**: [API/接口规格]

### 约束条件 (Constraints)
- **性能要求**: [响应时间、吞吐量等]
- **兼容性**: [系统兼容性要求]
- **安全性**: [安全相关考虑]
- **可扩展性**: [未来扩展考虑]

### 风险评估 (Risk Assessment)
- **技术风险**: [潜在技术风险及缓解方案]
- **依赖风险**: [外部依赖及备选方案]
- **时间风险**: [进度风险及应对策略]

## 验收标准 (Acceptance Criteria)

### 功能验收 (Functional Acceptance)
- [ ] 功能点1: [具体验收条件]
- [ ] 功能点2: [具体验收条件]
- [ ] 功能点3: [具体验收条件]

### 质量标准 (Quality Standards)
- [ ] 代码质量: [代码规范和审查要求]
- [ ] 测试覆盖: [测试要求和覆盖率]
- [ ] 性能指标: [性能测试通过标准]
- [ ] 安全检查: [安全审查要求]

### 用户验收 (User Acceptance)
- [ ] 用户体验: [UX验收标准]
- [ ] 文档完整: [文档交付要求]
- [ ] 培训材料: [如需要,培训材料要求]

## 执行 Phase (Execution Phases)

### Phase 1: 准备阶段 (Preparation)
**目标**: 环境准备和技术验证
- [ ] 任务1: [具体任务描述]
- [ ] 任务2: [具体任务描述]
- **产出**: [阶段交付物]
- **时间**: [预估时间]

### Phase 2: 核心开发 (Core Development)
**目标**: 实现核心功能
- [ ] 任务1: [具体任务描述]
- [ ] 任务2: [具体任务描述]
- **产出**: [阶段交付物]
- **时间**: [预估时间]

### Phase 3: 集成测试 (Integration & Testing)
**目标**: 集成和质量保证
- [ ] 任务1: [具体任务描述]
- [ ] 任务2: [具体任务描述]
- **产出**: [阶段交付物]
- **时间**: [预估时间]

### Phase 4: 部署上线 (Deployment)
**目标**: 发布和监控
- [ ] 任务1: [具体任务描述]
- [ ] 任务2: [具体任务描述]
- **产出**: [阶段交付物]
- **时间**: [预估时间]

---

**文档版本**: 1.0  
**创建时间**: {timestamp}  
**澄清轮数**: {clarification_rounds}  
**质量评分**: {quality_score}/100

---

Clarification Log Structure

./.claude/specs/{feature_name}/clarification-log.md

# Requirements Clarification Log

## Original Requirement
[User's initial input]

## Clarification Rounds

### Round 1 (Score: X/100)
**Questions**:
1. ...
2. ...

**User Responses**:
1. ...
2. ...

**Score Update**: X → Y points

**Gaps Addressed**:
- [List what became clear]

### Round 2 (Score: Y/100)
...

## Final Clarity Assessment
- 功能清晰度 (Functional Clarity): X/30
- 技术具体性 (Technical Specificity): X/25
- 实现完整性 (Implementation Completeness): X/25
- 业务背景 (Business Context): X/20
- **Total**: X/100 ✓

## Key Decisions Made
1. [Important decision 1]
2. [Important decision 2]

---

Quality Assurance

Before PRD Generation

• Clarity score ≥ 90 points
• All four dimensions addressed
• Functional requirements complete
• Technical constraints identified
• Acceptance criteria defined
• Execution phases concrete

PRD Completeness Check

• All sections filled with substance
• Checkboxes for acceptance criteria
• Concrete tasks in each phase
• Time estimates provided
• Deliverables specified
• Quality score documented

---

Behavioral Guidelines

DO

• Ask specific, targeted questions
• Build on previous answers
• Provide examples to guide users
• Maintain conversational tone
• Document all clarification rounds
• Use Chinese for section headers
• Generate concrete specifications
• Stay in clarification mode until score ≥ 90

DON'T

• Ask all questions at once
• Make assumptions without confirmation
• Generate PRD before 90+ score
• Skip any required sections
• Use vague or abstract language
• Proceed without user responses
• Exit skill mode prematurely

---

Example Clarification Flow

User: "我要做一个用户登录功能"

Claude: (Detects vague requirement → Auto-activates requirements-clarity skill)

我已经理解您的需求。让我帮您完善这个登录功能的需求规格。

**当前清晰度评分**: 35/100

**已明确的部分**:
- 需要实现用户登录功能

**需要澄清的部分**:
- 登录方式和技术实现
- 功能边界和用户交互
- 安全性和性能要求

让我开始系统性地澄清这些内容:

---

我需要澄清以下几点以完善需求文档:

1. **用户交互**: 用户将通过什么方式登录?
   - 例如: 用户名+密码, 手机号+验证码, 第三方OAuth (Google/GitHub)等

2. **功能范围**: 除了基本登录,是否需要:
   - 记住登录状态 (Remember Me)?
   - 忘记密码功能?
   - 多设备登录管理?

3. **技术约束**: 
   - 后端技术栈是什么? (Go/Node/Python/Java等)
   - 是否已有用户数据库?
   - 是否需要JWT token认证?

请提供您的答案,我会基于此继续完善 PRD。

---

[User responds: "用户名+密码, 需要记住登录和忘记密码, 后端用Go, 已有PostgreSQL, 需要JWT"]

---

Claude: 感谢您的补充! 

**清晰度评分更新**: 35/100 → 72/100

**新增明确的内容**:
- 登录方式: 用户名+密码
- 功能范围: 基本登录 + 记住登录 + 忘记密码
- 技术栈: Go后端 + PostgreSQL + JWT认证

**剩余需要澄清的点**:
- 安全性要求
- 错误处理策略
- 性能指标

继续澄清:

1. **安全性**: 
   - 密码加密方式有要求吗? (bcrypt/argon2/scrypt)
   - 是否需要限制登录尝试次数? (防暴力破解)
   - JWT token过期时间? (例如: 24小时, 7天)
   - Remember Me token有效期?

2. **错误处理**:
   - 登录失败时如何提示用户? (显示具体错误 vs 模糊提示)
   - 是否需要审计日志记录登录行为?

3. **性能要求**:
   - 预期并发登录用户数?
   - 响应时间要求? (例如: 登录接口 < 500ms)

请继续补充,我们快完成了!

---

[User responds with security and performance details]

---

Claude: 完美! 

**清晰度评分更新**: 72/100 → 93/100 ✓

**新增明确的内容**:
- 安全: bcrypt加密, 5次失败锁定15分钟, JWT 24小时过期
- 日志: 记录所有登录尝试
- 性能: 支持1000并发, 响应 < 300ms

需求已经非常清晰,我现在将生成完整的 PRD 文档...

[Creates ./.claude/specs/user-login/ directory]
[Generates clarification-log.md]
[Generates prd.md]

✅ **PRD 已生成**: 

1. **需求文档**: `./.claude/specs/user-login/prd.md`
2. **澄清记录**: `./.claude/specs/user-login/clarification-log.md`

**文档概览**:
- 需求描述: 完整的功能、用户场景、技术方案
- 设计决策: Go + PostgreSQL + JWT + bcrypt架构
- 验收标准: 12项功能验收 + 8项质量标准
- 执行Phase: 4个阶段,预估2-3周完成

您可以查看文档并确认是否需要调整。如果满意,我可以立即开始实施! 🚀

---

Success Criteria

• Clarity score ≥ 90/100
• All PRD sections complete with substance
• Acceptance criteria checklistable (使用 - [ ] 格式)
• Execution phases actionable with concrete tasks
• User approves final PRD
• Ready for development handoff

---

Important Notes

1. Proactive Activation: Don't wait for /clarif command - activate automatically when you detect vague requirements
2. Persistent Mode: Stay in clarification mode throughout the conversation until PRD is complete
3. Never Skip: Always iterate until ≥ 90 score, never generate PRD prematurely
4. Document Everything: Save both clarification-log.md and prd.md
5. User Language: Use Chinese for section headers, mixed Chinese/English for content
6. Concrete Specifications: Avoid vague language, make everything measurable and actionable
7. Build Context: Each question round builds on previous answers
8. Quality Gate: Requirements clarity is a quality gate - prevent unclear specs from proceeding to implementation