diff --git a/requirements-clarity/README.md b/requirements-clarity/README.md deleted file mode 100644 index 112da1d..0000000 --- a/requirements-clarity/README.md +++ /dev/null @@ -1,234 +0,0 @@ -# Requirements Clarity Plugin - -## Overview - -This Claude Code plugin automatically detects vague requirements and transforms them into crystal-clear Product Requirements Documents (PRDs) through systematic clarification. - -## Installation - -```bash -/plugin install requirements-clarity -``` - -Or add to your `.clauderc`: - -```json -{ - "plugins": { - "requirements-clarity": { - "enabled": true - } - } -} -``` - -## How It Works - -### Automatic Activation - -The plugin 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 agent - ↓ -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. Shows initial score (~30-40/100) -3. 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: 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**: -- Agent does NOT activate (requirement is already clear) -- Claude proceeds directly to implementation - -## Benefits - -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 - -## Command Alternative - -For manual invocation, use: -``` -/clarif -``` - -## Troubleshooting - -### Plugin Not Activating - -**Problem**: Claude doesn't enter clarification mode for vague requirements - -**Solutions**: -1. Verify plugin is installed: `/plugin list` -2. Check plugin is enabled in `.clauderc` -3. Ensure agent and command files exist in plugin directory -4. Try more explicit vague requirement: "add user feature" - -### Premature PRD Generation - -**Problem**: PRD generated before score reaches 90 - -**Solution**: This is a bug - agent instructions explicitly require ≥90 threshold. Review the clarification log to see actual score. - -## References - -- **Claude Code Plugins Documentation**: https://docs.claude.com/en/docs/claude-code/plugins -- **Article**: https://github.com/stellarlinkco/articles/blob/master/deep-agents-zh.md - -## Changelog - -### v1.0.0 (2025-10-21) -- Created plugin in correct `.claude-plugin/` directory format -- Added `marketplace.json` plugin metadata -- Commands in `commands/clarif.md` -- Agent in `agents/clarif-agent.md` -- All prompts in English -- Maintained 100-point scoring system and PRD structure -- Compatible with Claude Code plugin system - ---- - -**License**: MIT -**Author**: Claude Code Dev Workflows -**Homepage**: https://github.com/cexll/myclaude diff --git a/requirements-clarity/skills/SKILL.md b/requirements-clarity/skills/SKILL.md index dc6fbde..d9fdfec 100644 --- a/requirements-clarity/skills/SKILL.md +++ b/requirements-clarity/skills/SKILL.md @@ -63,8 +63,9 @@ Auto-activate when detecting vague requirements: **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) +3. Determine document version (default `1.0` unless user specifies otherwise) +4. Ensure `./docs/prds/` exists for PRD output +5. Perform initial clarity assessment (0-100) **Assessment Rubric**: ``` @@ -157,7 +158,7 @@ Please provide your answers, and I'll continue refining the PRD. **After Each User Response**: 1. Update clarity score -2. Document new information in clarification log +2. Capture new information in the working PRD outline 3. Identify remaining gaps 4. If score < 90: Continue with next round of questions 5. If score ≥ 90: Proceed to PRD generation @@ -182,12 +183,11 @@ Thank you for the additional information! Once clarity score ≥ 90, generate comprehensive PRD. -**Output Files**: +**Output File**: -1. **Clarification Log**: `./.claude/specs/{feature_name}/clarification-log.md` -2. **Final PRD**: `./.claude/specs/{feature_name}/prd.md` +1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md` -Use the `Write` tool to create both files. +Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`). ## PRD Document Structure @@ -287,47 +287,6 @@ Use the `Write` tool to create both files. **Quality Score**: {quality_score}/100 ``` -## Clarification Log Structure - -`./.claude/specs/{feature_name}/clarification-log.md` - -```markdown -# 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] -``` - ## Behavioral Guidelines ### DO @@ -335,7 +294,7 @@ Use the `Write` tool to create both files. - Build on previous answers - Provide examples to guide users - Maintain conversational tone -- Document all clarification rounds +- Summarize clarification rounds within the PRD - Use clear, professional English - Generate concrete specifications - Stay in clarification mode until score ≥ 90