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

# Requirements Clarity Skill

## Overview

This Claude Skill automatically detects vague requirements and transforms them into crystal-clear Product Requirements Documents (PRDs) through systematic clarification.

**Key Difference from `/clarif` Command**:
- **Command**: User must type `/clarif <requirement>` explicitly
- **Skill**: Claude automatically detects unclear requirements and activates clarification mode

## How It Works

### Automatic Activation

The skill activates when Claude detects:

1. **Vague Feature Requests**
   ```
   User: "add login feature"
   User: "implement payment system"
   User: "create user dashboard"
   ```

2. **Missing Technical Details**
   - No technology stack mentioned
   - No architecture or constraints specified
   - No integration points identified

3. **Incomplete Specifications**
   - No acceptance criteria
   - No success metrics
   - No edge cases or error handling

4. **Ambiguous Scope**
   - Unclear boundaries ("user management" - what exactly?)
   - No distinction between MVP and future features

### Clarification Process

```
User: "I want to implement a user login feature"
  ↓
Claude detects vague requirement
  ↓
Auto-activates requirements-clarity skill
  ↓
Initial assessment: 35/100 clarity score
  ↓
Round 1: Ask 2-3 targeted questions
  ↓
User responds
  ↓
Score update: 35 → 72
  ↓
Round 2: Continue clarifying gaps
  ↓
User responds
  ↓
Score update: 72 → 93 ✓ (≥90 threshold)
  ↓
Generate PRD files:
  - ./.claude/specs/user-login/prd.md
  - ./.claude/specs/user-login/clarification-log.md
```

## Scoring System (100 points)

| Dimension | Points | Criteria |
|-----------|--------|----------|
| **Functional Clarity** | 30 | Clear inputs/outputs (10), User interaction (10), Success criteria (10) |
| **Technical Specificity** | 25 | Tech stack (8), Integration points (8), Constraints (9) |
| **Implementation Completeness** | 25 | Edge cases (8), Error handling (9), Data validation (8) |
| **Business Context** | 20 | Problem statement (7), Target users (7), Success metrics (6) |

**Threshold**: ≥ 90 points required before PRD generation

## Output Structure

### 1. Clarification Log
`./.claude/specs/{feature-name}/clarification-log.md`

Documents the entire clarification conversation:
- Original requirement
- Each round of questions and answers
- Score progression
- Final assessment breakdown

### 2. Product Requirements Document
`./.claude/specs/{feature-name}/prd.md`

Structured PRD with four main sections:

#### Requirements Description
- Background: Business problem, target users, value proposition
- Feature Overview: Core functionality, boundaries, user scenarios
- Detailed Requirements: Inputs/outputs, interactions, data, edge cases

#### Design Decisions
- Technical Approach: Architecture, components, data storage, APIs
- Constraints: Performance, compatibility, security, scalability
- Risk Assessment: Technical, dependency, timeline risks

#### Acceptance Criteria
- Functional: Checklistable feature requirements
- Quality Standards: Code quality, testing, performance, security
- User Acceptance: UX, documentation, training

#### Execution Phases
- Phase 1: Preparation - Environment setup
- Phase 2: Core Development - Core implementation
- Phase 3: Integration & Testing - QA
- Phase 4: Deployment - Release

## Testing Guide

### Test Case 1: Vague Login Feature

**Input**:
```
"I want to implement a user login feature"
```

**Expected Behavior**:
1. Claude detects vague requirement
2. Announces activation of requirements-clarity skill
3. Shows initial score (~30-40/100)
4. Asks 2-3 questions about:
   - Login method (username+password, phone+OTP, OAuth?)
   - Functional scope (remember me, forgot password?)
   - Technology stack (backend language, database, auth method?)

**Expected Output**:
- Score improves to ~70+ after round 1
- Additional questions about security, error handling, performance
- Final score ≥ 90
- PRD generated in `./.claude/specs/user-login/`

### Test Case 2: Ambiguous E-commerce Feature

**Input**:
```
"add shopping cart to the website"
```

**Expected Behavior**:
1. Auto-activation (no tech stack, no UX details, no constraints)
2. Questions about:
   - Cart behavior (guest checkout? save for later? quantity limits?)
   - User experience (inline cart vs dedicated page?)
   - Backend integration (existing inventory system? payment gateway?)
   - Data persistence (session storage, database, local storage?)

**Expected Output**:
- Iterative clarification (2-3 rounds)
- Score progression: ~25 → ~65 → ~92
- PRD with concrete shopping cart specifications

### Test Case 3: Technical Implementation Request

**Input**:
```
"Refactor the authentication service to use JWT tokens"
```

**Expected Behavior**:
1. May NOT activate (already fairly specific)
2. If activates, asks about:
   - Token expiration strategy
   - Refresh token implementation
   - Migration plan from existing auth
   - Backward compatibility requirements

### Test Case 4: Clear Requirement (Should NOT Activate)

**Input**:
```
"Fix the null pointer exception in auth.go line 45 by adding a nil check before accessing user.Email"
```

**Expected Behavior**:
- Skill does NOT activate (requirement is already clear)
- Claude proceeds directly to implementation

## Comparison: Command vs Skill

| Aspect | `/clarif` Command | Requirements-Clarity Skill |
|--------|-------------------|----------------------------|
| **Activation** | Manual: `/clarif <requirement>` | Automatic: Claude detects vague specs |
| **User Awareness** | Must know command exists | Transparent, no learning curve |
| **Workflow** | User → Type command → Clarification | User → Express need → Auto-clarification |
| **Discoverability** | Requires documentation | Claude suggests when appropriate |
| **Use Case** | Explicit requirements review | Proactive quality gate |
| **File Location** | `commands/clarif.md` + `agents/clarif-agent.md` | `.claude/skills/requirements-clarity/SKILL.md` |

## Benefits of Skill Approach

1. **Proactive Quality Gate**: Prevents unclear specs from proceeding to implementation
2. **Zero Friction**: Users describe features naturally, no command syntax needed
3. **Context Awareness**: Claude recognizes ambiguity patterns automatically
4. **Persistent Mode**: Stays active throughout clarification conversation
5. **Better UX**: Natural conversation flow vs explicit command invocation

## Configuration

No configuration needed - the skill is automatically discovered by Claude Code when present in `.claude/skills/requirements-clarity/`.

**Skill Metadata** (in SKILL.md frontmatter):
```yaml
name: requirements-clarity
description: Automatically clarify vague requirements into actionable PRDs
activation_triggers:
  - User describes feature without technical details
  - Request lacks acceptance criteria
  - Scope is ambiguous
  - Missing technology stack
tools: Read, Write, Glob, Grep, TodoWrite
```

## Troubleshooting

### Skill Not Activating

**Problem**: Claude doesn't enter clarification mode for vague requirements

**Solutions**:
1. Verify `.claude/skills/requirements-clarity/SKILL.md` exists
2. Check YAML frontmatter is valid
3. Ensure activation_triggers are defined
4. Try more explicit vague requirement: "add user feature"

### Premature PRD Generation

**Problem**: PRD generated before score reaches 90

**Solution**: This is a bug - SKILL.md explicitly requires ≥90 threshold. Review the clarification log to see actual score.

### Over-Clarification

**Problem**: Claude asks too many questions for simple features

**Expected**: This is by design - better to over-clarify than under-specify. If the requirement is truly simple, answer questions quickly to reach 90+ score faster.

## Migration from `/clarif` Command

The `/clarif` command in `development-essentials/commands/clarif.md` can coexist with this skill:

- **Skill**: Automatic activation for new, unclear requirements
- **Command**: Explicit review of existing requirements

**Recommended Workflow**:
1. User describes feature naturally
2. Skill auto-activates and generates PRD
3. (Optional) User runs `/clarif <existing-prd>` to review/refine

## Examples

### Example 1: Login Feature (Full Flow)

See full example in SKILL.md under "Example Clarification Flow"

**Summary**:
- Input: "I want to implement a user login feature"
- Round 1: Login method, scope, tech stack → Score 35→72
- Round 2: Security, error handling, performance → Score 72→93
- Output: Complete PRD with bcrypt, JWT, PostgreSQL, Go backend

### Example 2: API Endpoint

**Input**: "create an API to get user profile"

**Round 1** (Score: 28/100):
```
Q1: What information should the API return? (name, email, avatar, preferences?)
Q2: Authentication required? (JWT, session, API key?)
Q3: Response format? (JSON, XML?) Any pagination?
```

**Round 2** (Score: 75/100):
```
Q1: Error handling: What if user not found? (404, custom error?)
Q2: Performance: Caching strategy? Expected QPS?
Q3: Privacy: Any fields that should be filtered based on requester?
```

**Round 3** (Score: 91/100):
```
PRD Generated:
- Endpoint: GET /api/v1/users/:id
- Auth: JWT required
- Response: JSON with name, email, avatar, bio
- Caching: Redis, 5min TTL
- Rate limit: 100 req/min per user
```

## References

- **Claude Skills Documentation**: https://docs.claude.com/en/docs/claude-code/skills
- **Anthropic Skills Announcement**: https://www.anthropic.com/news/skills
- **Original `/clarif` Command**: `development-essentials/commands/clarif.md`
- **Original Clarification Agent**: `development-essentials/agents/clarif-agent.md`

## Changelog

### v1.0 (2025-10-20)
- Initial skill implementation
- Ported clarification logic from `/clarif` command
- Added automatic activation triggers
- Implemented 100-point scoring system
- Created structured PRD template with Requirements/Design/Acceptance/Execution sections
- Added comprehensive test cases and examples
- Translated to English for plugin compatibility