@vpxa/aikit 0.1.145 → 0.1.147

package/scaffold/dist/definitions/skills/requirements-clarity.mjs

@@ -10,325 +10,109 @@ metadata:
   relatedSkills: [brainstorming]
 ---
 
-# Requirements Clarity Skill
+# Requirements Clarity
 
-## Description
+## When to Skip
 
-Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.
-
-
-## Instructions
-
-When invoked, detect 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**:
+Do NOT activate when:
 - Specific file paths mentioned (e.g., "auth.go:45")
-- Code snippets included
-- Existing functions/classes referenced
+- Code snippets or existing functions/classes referenced
 - Bug fixes with clear reproduction steps
+- Task is a single-file change with obvious scope
 
-## Core Principles
+## Protocol
 
-1. **Systematic Questioning**
-   - Ask focused, specific questions
-   - One category at a time (2-3 questions per round)
-   - Build on previous answers
-   - Avoid overwhelming users
+### 1. YAGNI/KISS Gate
 
-2. **Quality-Driven Iteration**
-   - Continuously assess clarity score (0-100)
-   - Identify gaps systematically
-   - Iterate until ≥ 90 points
-   - Document all clarification rounds
+Before ANY scoring, ask:
+- **Why?** — Is this needed now? YAGNI check.
+- **Simpler?** — Is there a simpler approach? KISS check.
 
-3. **Actionable Output**
-   - Generate concrete specifications
-   - Include measurable acceptance criteria
-   - Provide executable phases
-   - Enable direct implementation
+If the answers show the feature is not needed now, should be deferred, or has a trivial solution, advise that directly instead of continuing to scoring.
 
-## Clarification Process
+### 2. Score (0-100)
 
-### Step 1: Initial Requirement Analysis
+Assess the requirement against this rubric:
 
-**Input**: User's requirement description
+| Category | Points | Criteria |
+|----------|--------|----------|
+| Functional Clarity | /30 | Clear inputs/outputs (10), user interaction defined (10), success criteria stated (10) |
+| Technical Specificity | /25 | Tech stack mentioned (8), integration points (8), constraints specified (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) |
 
-**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 \`.spec/{feature_name}/\` exists for PRD output
-5. Perform initial clarity assessment (0-100)
+If you present this rubric or a score update to the user, use \`present({ format: 'html' })\` with a metrics block when visual formatting would help.
 
-**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
-
-
-If you present this rubric or a requirements scorecard to the user, use \`present({ format: 'html' })\` to display a rich dashboard when visual formatting would help.
-Implementation Completeness: /25 points
-- Edge cases considered: 8 pts
-- Error handling mentioned: 9 pts
-- Data validation specified: 8 pts
+### 3. Iterate Until ≥ 90
 
-Business Context: /20 points
-- Problem statement clear: 7 pts
-- Target users identified: 7 pts
-- Success metrics defined: 6 pts
-\`\`\`
+For each clarification round:
+1. Score the current requirement.
+2. Identify the 2-3 highest-impact gaps.
+3. Ask focused questions for one category at a time.
+4. Update the score after each user response.
+5. Capture clarified details in a working outline.
+6. Repeat until the score is at least 90.
 
-**Initial Response Format**:
-\`\`\`markdown
-I understand your requirement. Let me help you refine this specification.
+Prefer short, targeted questions over long questionnaires. Build on previous answers instead of repeating the whole requirement.
 
-**Current Clarity Score**: X/100
+**HARD RULE:** Do not generate the requirements document with a score below 90.
 
-**Clear Aspects**:
-- [List what's clear]
+### 4. Generate Requirements Document
 
-**Needs Clarification**:
-- [List gaps]
+**Output path (flow-aware):**
+- If a flow is active: \`flow({ action: 'status' })\` → write to \`{{artifacts_path}}/requirements.md\`
+- If no flow active: write to \`.spec/{feature_name}/requirements.md\`
 
-Let me systematically clarify these points...
+To detect active flow:
 \`\`\`
-
-### 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.
+const flowStatus = flow({ action: 'status' });
+if (flowStatus.active) {
+  // Output to: .flows/{topic}/.spec/requirements.md
+  outputPath = \`\${flowStatus.artifactsPath}/requirements.md\`;
+} else {
+  outputPath = \`.spec/\${featureName}/requirements.md\`;
+}
 \`\`\`
 
-**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..."]
+Use \`create_file\` to save the document after the score reaches 90 or higher.
+
+Required structure:
+- **Requirements Description**
+  - Background
+  - Feature overview
+  - Detailed requirements
+  - Edge cases
+- **Design Decisions**
+  - Technical approach
+  - Constraints
+  - Risk assessment
+- **Acceptance Criteria**
+  - Functional acceptance checkboxes
+  - Quality standards
+  - User acceptance
+- **Execution Phases**
+  - Preparation
+  - Core development
+  - Integration and testing
+  - Deployment
+
+Each section must contain concrete, implementation-ready content. Do not leave placeholders.
+
+Footer fields:
+- Document Version
+- Created timestamp
+- Clarification Rounds count
+- Quality Score /100
+
+**After writing:** Also store a compact summary in flow-scoped knowledge for downstream step consumption:
 \`\`\`
-
-### Step 4: PRD Generation
-
-Once clarity score ≥ 90, generate comprehensive PRD.
-
-**Output File**:
-
-1. **Final PRD**: \`.spec/{feature_name}/requirements.md\`
-
-Use \`create_file\` to save 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
+knowledge({ 
+  action: "remember", 
+  scope: "flow", 
+  category: "context",
+  title: "Requirements: <feature>",
+  content: "Score: <X>/100\\nKey Requirements:\\n- <req1>\\n- <req2>\\nAcceptance Criteria:\\n- <criteria1>\\nConstraints:\\n- <constraint1>"
+})
 \`\`\`
-
-## 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
+This ensures downstream steps (Spec, Plan, Implementation) can access requirements via \`withdraw\` even without reading the file.
 `}];export{e as default};