From d19b70896dd5ff53a45fa0db570fb7005b091b25 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:08:31 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 ++ README.md | 3 + plugin.lock.json | 45 ++++++ skills/SKILL.md | 323 +++++++++++++++++++++++++++++++++++++ 4 files changed, 383 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..2a0caa9 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "requirements-clarity", + "description": "Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Claude Code Dev Workflows", + "email": "contact@example.com" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..7b8b6f2 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# requirements-clarity + +Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..3de0c67 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:cexll/myclaude:requirements-clarity/", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "b01f231152b67fe745c3b69b900b3d717be3e975", + "treeHash": "488f74b611a08e41545a015177b814f3e8ea55504c4c44d4b6839d637eaf3e91", + "generatedAt": "2025-11-28T10:14:58.731887Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "requirements-clarity", + "description": "Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system", + "version": null + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "0e4c35ee4be9e2720a985b07d51a42a905074513a95cc1e5cf436f6b7c395add" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "1b0ae4c232ea8d59add3ab8d42b86bdca689afd6f035bcf94ccb4dbc97e186ce" + }, + { + "path": "skills/SKILL.md", + "sha256": "dfd1bf80ea05cda991d39fdbcd7433511b03868a21f816f6450ed1f80976691b" + } + ], + "dirSha256": "488f74b611a08e41545a015177b814f3e8ea55504c4c44d4b6839d637eaf3e91" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/SKILL.md b/skills/SKILL.md new file mode 100644 index 0000000..0fc5394 --- /dev/null +++ b/skills/SKILL.md @@ -0,0 +1,323 @@ +--- +name: Requirements Clarity +description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding. +--- + +# Requirements Clarity Skill + +## Description + +Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system. + +## Activation + +Auto-activate when detecting vague requirements: + +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" + +**Do NOT activate when**: +- Specific file paths mentioned (e.g., "auth.go:45") +- Code snippets included +- Existing functions/classes referenced +- Bug fixes with clear reproduction steps + +## 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. 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**: +``` +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**: +```markdown +I understand your requirement. Let me help you refine this specification. + +**Current Clarity Score**: X/100 + +**Clear Aspects**: +- [List what's clear] + +**Needs Clarification**: +- [List gaps] + +Let me systematically clarify these points... +``` + +### 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**: +```markdown +I need to clarify the following points to complete the requirements document: + +1. **[Category]**: [Specific question]? + - For example: [Example if helpful] + +2. **[Category]**: [Specific question]? + +3. **[Category]**: [Specific question]? + +Please provide your answers, and I'll continue refining the PRD. +``` + +**After Each User Response**: +1. Update clarity score +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 + +**Score Update Format**: +```markdown +Thank you for the additional information! + +**Clarity Score Update**: X/100 → Y/100 + +**New Clarified Content**: +- [Summarize new information] + +**Remaining Points to Clarify**: +- [List remaining gaps if score < 90] + +[If score < 90: Continue with next round of questions] +[If score ≥ 90: "Perfect! I will now generate the complete PRD document..."] +``` + +### Step 4: PRD Generation + +Once clarity score ≥ 90, generate comprehensive PRD. + +**Output File**: + +1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md` + +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 + +```markdown +# {Feature Name} - Product Requirements Document (PRD) + +## Requirements Description + +### Background +- **Business Problem**: [Describe the business problem to solve] +- **Target Users**: [Target user groups] +- **Value Proposition**: [Value this feature brings] + +### Feature Overview +- **Core Features**: [List of main features] +- **Feature Boundaries**: [What is and isn't included] +- **User Scenarios**: [Typical usage scenarios] + +### Detailed Requirements +- **Input/Output**: [Specific input/output specifications] +- **User Interaction**: [User operation flow] +- **Data Requirements**: [Data structures and validation rules] +- **Edge Cases**: [Edge case handling] + +## Design Decisions + +### Technical Approach +- **Architecture Choice**: [Technical architecture decisions and rationale] +- **Key Components**: [List of main technical components] +- **Data Storage**: [Data models and storage solutions] +- **Interface Design**: [API/interface specifications] + +### Constraints +- **Performance Requirements**: [Response time, throughput, etc.] +- **Compatibility**: [System compatibility requirements] +- **Security**: [Security considerations] +- **Scalability**: [Future expansion considerations] + +### Risk Assessment +- **Technical Risks**: [Potential technical risks and mitigation plans] +- **Dependency Risks**: [External dependencies and alternatives] +- **Schedule Risks**: [Timeline risks and response strategies] + +## Acceptance Criteria + +### Functional Acceptance +- [ ] Feature 1: [Specific acceptance conditions] +- [ ] Feature 2: [Specific acceptance conditions] +- [ ] Feature 3: [Specific acceptance conditions] + +### Quality Standards +- [ ] Code Quality: [Code standards and review requirements] +- [ ] Test Coverage: [Testing requirements and coverage] +- [ ] Performance Metrics: [Performance test pass criteria] +- [ ] Security Review: [Security review requirements] + +### User Acceptance +- [ ] User Experience: [UX acceptance criteria] +- [ ] Documentation: [Documentation delivery requirements] +- [ ] Training Materials: [If needed, training material requirements] + +## Execution Phases + +### Phase 1: Preparation +**Goal**: Environment preparation and technical validation +- [ ] Task 1: [Specific task description] +- [ ] Task 2: [Specific task description] +- **Deliverables**: [Phase deliverables] +- **Time**: [Estimated time] + +### Phase 2: Core Development +**Goal**: Implement core functionality +- [ ] Task 1: [Specific task description] +- [ ] Task 2: [Specific task description] +- **Deliverables**: [Phase deliverables] +- **Time**: [Estimated time] + +### Phase 3: Integration & Testing +**Goal**: Integration and quality assurance +- [ ] Task 1: [Specific task description] +- [ ] Task 2: [Specific task description] +- **Deliverables**: [Phase deliverables] +- **Time**: [Estimated time] + +### Phase 4: Deployment +**Goal**: Release and monitoring +- [ ] Task 1: [Specific task description] +- [ ] Task 2: [Specific task description] +- **Deliverables**: [Phase deliverables] +- **Time**: [Estimated time] + +--- + +**Document Version**: 1.0 +**Created**: {timestamp} +**Clarification Rounds**: {clarification_rounds} +**Quality Score**: {quality_score}/100 +``` + +## Behavioral Guidelines + +### DO +- Ask specific, targeted questions +- Build on previous answers +- Provide examples to guide users +- Maintain conversational tone +- Summarize clarification rounds within the PRD +- Use clear, professional English +- 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 + +## Success Criteria + +- Clarity score ≥ 90/100 +- All PRD sections complete with substance +- Acceptance criteria checklistable (using `- [ ]` format) +- Execution phases actionable with concrete tasks +- User approves final PRD +- Ready for development handoff