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):

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