@windagency/valora 2.0.1

package/data/prompts/07_documentation/apply-specification-refinement.md

@@ -0,0 +1,304 @@
+---
+id: documentation.apply-specification-refinement
+version: 1.0.0
+category: documentation
+experimental: true
+name: Apply Specification Refinement
+description: Merge user clarifications into refined specifications and output final document
+tags:
+  - specifications
+  - refinement
+  - documentation
+  - merge
+model_requirements:
+  min_context: 128000
+  recommended:
+    - claude-haiku-4.5
+agents:
+  - product-manager
+dependencies:
+  requires:
+    - context.use-modern-cli-tools
+    - context.understand-intent
+    - onboard.refine-specifications
+    - review.validate-completeness
+inputs:
+  - name: refined_specifications
+    description: Refined specifications from onboard.refine-specifications
+    type: string
+    required: true
+  - name: clarity_score
+    description: Clarity score from onboard.refine-specifications
+    type: number
+    required: true
+  - name: validation_results
+    description: Validation results from review.validate-completeness
+    type: object
+    required: true
+  - name: user_answers
+    description: User answers to clarifying questions (from interactive mode)
+    type: object
+    required: false
+  - name: user_answers_summary
+    description: Summary of user answers for inclusion in the document
+    type: string
+    required: false
+  - name: output_file
+    description: Path to output file (default knowledge-base/FUNCTIONAL.md)
+    type: string
+    required: false
+outputs:
+  - final_specifications
+  - changes_summary
+  - clarifications_applied
+tokens:
+  avg: 6000
+  max: 12000
+  min: 2000
+---
+
+# Apply Specification Refinement
+
+## CRITICAL: Output Format Requirement
+
+**You MUST output ONLY valid JSON. Do NOT output markdown, do NOT wrap in code blocks, do NOT add any text before or after the JSON.**
+
+Your response must be a single JSON object matching the schema defined in the "Output Format" section at the end of this prompt. Start directly with `{` and end with `}`.
+
+## Objective
+
+1. Take the refined specifications from the onboard stage
+2. Incorporate user answers to clarifying questions (if provided)
+3. Update the specification document with clarifications applied
+4. Generate a summary of changes made
+5. Output the final specification document ready for saving
+
+## Instructions
+
+### Step 1: Analyze User Clarifications
+
+If `user_answers` is provided, extract the key decisions made by the user:
+
+**For each user answer:**
+
+- Identify which section of the specification it affects
+- Determine how the answer resolves ambiguity
+- Note if the answer changes any assumptions made
+
+**Example user answers structure:**
+
+```json
+{
+	"q1": {
+		"question": "Should dependencies be auto-detected or manually defined?",
+		"answer": "Hybrid approach (auto-detect with manual override)",
+		"was_custom": false
+	},
+	"q2": {
+		"question": "What authentication method should be used?",
+		"answer": "OAuth 2.0 with Google and GitHub providers",
+		"was_custom": true
+	}
+}
+```
+
+### Step 2: Map Answers to Specification Sections
+
+For each user answer, identify the affected sections:
+
+| Answer Topic        | Affected Sections                                               |
+| ------------------- | --------------------------------------------------------------- |
+| Authentication      | Functional Requirements, Non-Functional (Security), Constraints |
+| Data handling       | Functional Requirements, Non-Functional (Performance)           |
+| User interface      | Functional Requirements, Success Criteria                       |
+| Integration         | Dependencies, Constraints, Technical Notes                      |
+| Scope decisions     | In Scope, Out of Scope                                          |
+| Performance targets | Non-Functional Requirements, Success Criteria                   |
+
+### Step 3: Update Specification Content
+
+Apply user clarifications to the specification:
+
+1. **Update affected requirements** with specific decisions
+2. **Remove resolved items from Open Questions**
+3. **Convert assumptions to confirmed decisions** where applicable
+4. **Add "User Clarifications" section** documenting decisions made
+
+**User Clarifications Section Format:**
+
+```markdown
+---
+
+## User Clarifications
+
+The following decisions were made during the refinement process:
+
+| Question | Decision | Impact |
+|----------|----------|--------|
+| [Question text] | [User's answer] | [Affected requirements/sections] |
+
+**Applied on**: [ISO timestamp]
+**Mode**: Interactive
+
+---
+```
+
+### Step 4: Recalculate Clarity Score
+
+After applying clarifications:
+
+- Increase clarity score based on questions resolved
+- Each P0 question resolved: +5-10%
+- Each P1 question resolved: +3-5%
+- Each P2 question resolved: +1-2%
+
+Maximum clarity score: 100%
+
+### Step 5: Build Changes Summary
+
+Generate a human-readable summary of changes:
+
+```markdown
+# Specification Refinement Applied
+
+## Summary
+
+- **Final Clarity Score**: [XX]% (was [YY]%)
+- **Questions Resolved**: [N] out of [M]
+- **Sections Updated**: [List of sections]
+
+## User Decisions Applied
+
+### [Question 1]
+
+- **Decision**: [User's answer]
+- **Applied to**: [Section(s) affected]
+- **Change**: [What was updated]
+
+### [Question 2]
+
+...
+
+## Remaining Open Questions
+
+- [Any unresolved questions]
+
+## Assumptions Validated
+
+- ✅ [Assumption confirmed by user answer]
+- ✅ [Assumption confirmed by user answer]
+
+---
+
+**File**: [output_file path]
+**Status**: Ready for PRD generation
+```
+
+### Step 6: Build Final Specification
+
+Combine the original specification with all updates:
+
+1. Keep original structure and formatting
+2. Insert User Clarifications section before "Open Questions"
+3. Update requirements based on decisions
+4. Update clarity metadata in header
+5. Add refinement timestamp
+
+**Updated Header:**
+
+```markdown
+**Status**: ✅ REFINED
+**Clarity Score**: [Updated score]%
+**Last Refined**: [ISO timestamp]
+**Refinement Mode**: [Interactive/Auto]
+```
+
+## Output Format
+
+**CRITICAL**: The `final_specifications` field MUST contain the COMPLETE updated specification document.
+
+**IMPORTANT**: Do NOT include code block markers in your actual response. Start directly with `{`.
+
+```json
+{
+	"final_specifications": "# Project Specification: [Name]\n\n**Purpose**: ...\n**Status**: ✅ REFINED\n**Clarity Score**: 95%\n**Last Refined**: 2025-01-28T10:30:00Z\n...\n\n## User Clarifications\n\n| Question | Decision | Impact |\n|----------|----------|--------|\n| Should dependencies be auto-detected? | Hybrid approach | FR-002, FR-003 |\n\n...[rest of specification with updates applied]...",
+	"changes_summary": "# Specification Refinement Applied\n\n## Summary\n- **Final Clarity Score**: 95% (was 82%)\n- **Questions Resolved**: 3 out of 3\n...",
+	"clarifications_applied": [
+		{
+			"question_id": "q1",
+			"question": "Should dependencies be auto-detected or manually defined?",
+			"answer": "Hybrid approach (auto-detect with manual override)",
+			"sections_updated": ["Functional Requirements", "Technical Notes"],
+			"impact_description": "Updated FR-002 to specify hybrid dependency detection"
+		},
+		{
+			"question_id": "q2",
+			"question": "What authentication method should be used?",
+			"answer": "OAuth 2.0 with Google and GitHub",
+			"sections_updated": ["Functional Requirements", "Non-Functional Requirements", "Constraints"],
+			"impact_description": "Added OAuth providers to FR-001, updated security requirements"
+		}
+	],
+	"clarity_score_final": 0.95,
+	"clarity_score_improvement": 0.13,
+	"questions_resolved": 3,
+	"questions_remaining": 0
+}
+```
+
+## Handling No User Answers
+
+If `user_answers` is not provided or empty (auto mode):
+
+1. Keep specification as-is from the onboard stage
+2. Note in changes_summary that no interactive clarifications were made
+3. Keep assumptions section prominent
+4. Set `clarifications_applied` to empty array
+
+**Auto mode output:**
+
+```json
+{
+	"final_specifications": "[Original specification with REFINED status]",
+	"changes_summary": "# Specification Refinement Applied\n\n## Summary\n- **Mode**: Auto (no interactive clarifications)\n- **Clarity Score**: [XX]%\n- **Assumptions Made**: [N] (see Assumptions section)\n\n## Note\nNo interactive clarifications were provided. The specification contains assumptions that should be validated before proceeding to PRD.\n\n**High-Risk Assumptions**: [List any flagged]",
+	"clarifications_applied": [],
+	"clarity_score_final": 0.85,
+	"clarity_score_improvement": 0,
+	"questions_resolved": 0,
+	"questions_remaining": 5
+}
+```
+
+## Success Criteria
+
+- ✅ User answers correctly mapped to specification sections
+- ✅ Specification updated with all clarifications
+- ✅ Open Questions section updated (resolved items removed)
+- ✅ Clarity score recalculated
+- ✅ Changes summary clearly describes what was updated
+- ✅ Final specification is complete and well-formatted
+- ✅ Output is valid JSON with all required fields
+
+## Rules
+
+**DO**:
+
+- ✅ Preserve all original specification content not affected by clarifications
+- ✅ Make updates traceable (User Clarifications section)
+- ✅ Recalculate clarity score accurately
+- ✅ Generate clear, actionable changes summary
+- ✅ Handle both interactive and auto mode gracefully
+
+**DON'T**:
+
+- ❌ NEVER remove content not related to user answers
+- ❌ NEVER fabricate user answers or decisions
+- ❌ NEVER skip the changes_summary field
+- ❌ NEVER output partial specification content
+- ❌ NEVER change formatting or structure outside affected sections
+
+## REMINDER: Output Requirements
+
+**Output ONLY the JSON object. No markdown, no code blocks, no explanatory text. Start directly with `{` and end with `}`.**
+
+The `final_specifications` field must contain the COMPLETE updated specification document.

package/data/prompts/07_documentation/apply-task-refinement.md

@@ -0,0 +1,389 @@
+---
+id: documentation.apply-task-refinement
+version: 1.1.0
+category: documentation
+experimental: true
+name: Apply Task Refinement
+description: Merge refined task into BACKLOG.md and output for approval
+tags:
+  - backlog
+  - task-refinement
+  - documentation
+  - merge
+model_requirements:
+  min_context: 128000
+  recommended:
+    - claude-haiku-4.5
+agents:
+  - product-manager
+dependencies:
+  requires:
+    - context.load-task
+    - onboard.refine-requirements
+    - review.validate-testability
+    - context.use-modern-cli-tools
+inputs:
+  - name: task_context
+    description: Original task details from context.load-task
+    type: object
+    required: true
+  - name: refinement
+    description: Refined requirements from onboard.refine-requirements
+    type: object
+    required: true
+  - name: validation
+    description: Validation results from review.validate-testability
+    type: object
+    required: true
+  - name: backlog_file
+    description: Path to BACKLOG.md file
+    type: string
+    required: true
+  - name: user_answers
+    description: User answers to clarifying questions (from interactive mode)
+    type: object
+    required: false
+  - name: user_answers_summary
+    description: Summary of user answers for inclusion in changes summary
+    type: string
+    required: false
+outputs:
+  - changes_summary
+  - backlog_document
+  - updated_task
+tokens:
+  avg: 8000
+  max: 15000
+  min: 3000
+---
+
+# Apply Task Refinement
+
+## CRITICAL: Output Format Requirement
+
+**You MUST output ONLY valid JSON. Do NOT output markdown, do NOT wrap in code blocks, do NOT add any text before or after the JSON.**
+
+Your response must be a single JSON object matching the schema defined in the "Output Format" section at the end of this prompt. Start directly with `{` and end with `}`.
+
+## Objective
+
+1. Read the existing BACKLOG.md file
+2. Generate a summary of proposed changes
+3. Merge the refined task into the BACKLOG.md
+4. Output the complete merged document for user approval
+
+## Instructions
+
+### Step 1: Read Existing BACKLOG.md
+
+Use the `read_file` tool to read the content from the `backlog_file` path provided in inputs. This will give you the current BACKLOG.md content to merge with.
+
+### Step 2: Extract Task ID and Locate Task Section
+
+From `task_context`, extract the task ID (e.g., "FE001").
+
+Find the task section in the BACKLOG.md content. Task sections typically follow this pattern:
+
+```markdown
+#### [TASK-ID]: [Title]
+
+**Requirement(s)**: [FR-XXX]
+**Priority**: [P0/P1/P2]
+...
+```
+
+### Step 3: Generate Changes Summary
+
+Compare the original task with the refined version to create a human-readable summary:
+
+**Include in summary:**
+
+- Task ID and title
+- What changed (description, acceptance criteria, scope, etc.)
+- Number of new/modified acceptance criteria
+- Testability score achieved
+- Assumptions made
+- User clarifications (if `user_answers` provided from interactive mode)
+
+**Format the summary as markdown** (this will be displayed to the user):
+
+```markdown
+# Proposed Changes to Task [TASK-ID]: [Title]
+
+## Summary
+
+- **Testability Score**: [XX]%
+- **New Acceptance Criteria**: [N] added
+- **Modified Criteria**: [N] refined
+- **Assumptions Made**: [N] (with [N] high-risk)
+
+## Key Changes
+
+### Acceptance Criteria
+
+- ✅ Added: [criterion description]
+- 📝 Refined: [original] → [new]
+
+### Scope Clarified
+
+- In scope: [items]
+- Out of scope: [items]
+
+### Testing Strategy
+
+- Unit tests: [coverage]
+- Integration tests: [coverage]
+- E2E tests: [scenarios]
+
+## Assumptions
+
+1. [Assumption] - Confidence: [High/Medium/Low]
+
+## User Clarifications (if interactive mode)
+
+[Include user_answers_summary if provided, or note "N/A - Auto mode"]
+
+---
+
+**File**: [backlog_file]
+**Task**: [TASK-ID]
+```
+
+### Step 4: Build Updated Task Section
+
+Create the updated task section in BACKLOG.md format:
+
+```markdown
+#### [TASK-ID]: [Title]
+
+**Requirement(s)**: [FR-XXX]
+**Priority**: [P0/P1/P2]
+**Domain**: [Domain]
+**Effort**: [XS/S/M/L] ([X] days)
+**Dependencies**: [TASK-XXX] or [None]
+**Last Refined**: [ISO timestamp]
+**Testability Score**: [XX]%
+
+**Description**:
+[Refined description from refinement stage]
+
+**Acceptance Criteria**:
+
+1. Given [context], when [action], then [expected outcome]
+2. [Additional criteria from refinement...]
+
+**Scope**:
+
+- In scope: [items]
+- Out of scope: [items]
+
+**Technical Notes**:
+
+- [Implementation hints from refinement]
+- [Architecture considerations]
+
+**Testing Requirements**:
+
+- Unit: [requirements]
+- Integration: [requirements]
+- E2E: [scenarios]
+
+---
+```
+
+### Step 5: Merge Into BACKLOG.md (CRITICAL - Data Integrity)
+
+**⚠️ WARNING: You MUST preserve ALL content outside the target task section. Data loss is unacceptable.**
+
+#### Task Section Boundaries
+
+A task section in BACKLOG.md:
+
+- **STARTS** with: `#### [TASK-ID]: [Title]` (e.g., `#### FE001: Implement task creation form`)
+- **ENDS** at: The next `#### ` heading OR the next `### ` heading OR `---` separator OR end of file
+
+#### Merge Algorithm (Follow Exactly)
+
+```
+1. CONTENT_BEFORE = Everything from start of file UP TO (but not including) "#### [TASK-ID]:"
+2. UPDATED_TASK = The new refined task section you created in Step 4
+3. CONTENT_AFTER = Everything AFTER the original task section ends (starting from the next heading or separator)
+4. MERGED = CONTENT_BEFORE + UPDATED_TASK + CONTENT_AFTER
+```
+
+#### Example Merge
+
+**Original BACKLOG.md (simplified):**
+
+```markdown
+# Project Backlog
+
+...header content...
+
+### Phase 0: Foundation
+
+#### FE001: Implement task creation form
+
+**Priority**: P0
+...old task content...
+
+---
+
+#### FE002: Add description field
+
+...FE002 content...
+
+### Phase 1: Core Features
+
+...more content...
+```
+
+**After Merge (only FE001 replaced):**
+
+```markdown
+# Project Backlog
+
+...header content... ← PRESERVED EXACTLY
+
+### Phase 0: Foundation ← PRESERVED EXACTLY
+
+#### FE001: Implement task creation form
+
+**Priority**: P0
+**Last Refined**: 2025-01-22T10:30:00Z
+...NEW refined task content...
+
+---
+
+#### FE002: Add description field ← PRESERVED EXACTLY
+
+...FE002 content... ← PRESERVED EXACTLY
+
+### Phase 1: Core Features ← PRESERVED EXACTLY
+
+...more content... ← PRESERVED EXACTLY
+```
+
+#### Integrity Checks
+
+Before outputting, verify:
+
+- [ ] All other tasks are UNCHANGED
+- [ ] All phase headings are PRESERVED
+- [ ] Header/metadata sections are PRESERVED
+- [ ] Summary tables are PRESERVED
+- [ ] Dependency graphs are PRESERVED
+- [ ] Only the target task section was modified
+
+**IMPORTANT**: The `backlog_document` output must contain the COMPLETE BACKLOG.md content with ONLY the target task merged in. Everything else must be byte-for-byte identical to the original.
+
+### Step 6: Build Updated Task Object
+
+Create a structured object with all the refined task details for reference.
+
+## Output Format
+
+**CRITICAL**: The `backlog_document` field MUST contain the COMPLETE merged BACKLOG.md content. This is the primary content that will be written to the file after user approval.
+
+**IMPORTANT**: The example below is for illustration only. Do NOT include the ` ```json ` and ` ``` ` code block markers in your actual response. Start directly with `{`.
+
+```json
+{
+	"changes_summary": "# Proposed Changes to Task FE001: Implement task creation form\\n\\n## Summary\\n- **Testability Score**: 88%\\n- **New Acceptance Criteria**: 3 added\\n...\\n",
+	"backlog_document": "# Project Backlog: [Project Name]\\n\\n**Generated**: [timestamp]\\n...\\n\\n#### FE001: Implement task creation form\\n\\n**Requirement(s)**: FR-001\\n**Priority**: P0\\n**Last Refined**: 2025-01-22T10:30:00Z\\n**Testability Score**: 88%\\n\\n**Description**:\\n[Refined description]\\n\\n**Acceptance Criteria**:\\n1. [Refined criterion 1]\\n2. [Refined criterion 2]\\n...\\n\\n---\\n\\n[REST OF BACKLOG.md CONTENT UNCHANGED]\\n",
+	"updated_task": {
+		"id": "FE001",
+		"title": "Task title",
+		"description": "Refined description",
+		"priority": "P0",
+		"domain": "Frontend",
+		"effort": "XS",
+		"acceptance_criteria": ["Given [context], when [action], then [outcome]"],
+		"scope_in": ["item 1"],
+		"scope_out": ["excluded 1"],
+		"dependencies": [],
+		"technical_notes": ["note 1"],
+		"testing_strategy": {
+			"unit": "coverage details",
+			"integration": "coverage details",
+			"e2e": "scenarios"
+		},
+		"refinement_metadata": {
+			"refined_at": "2025-01-22T10:30:00Z",
+			"testability_score": 0.88,
+			"assumptions_count": 3,
+			"high_risk_assumptions": 1
+		}
+	}
+}
+```
+
+## Key Requirements
+
+1. **`backlog_document` is REQUIRED** - Must contain the complete merged BACKLOG.md
+2. **`changes_summary` is REQUIRED** - Human-readable markdown summary of changes
+3. **`updated_task` is REQUIRED** - Structured object with refined task details
+
+## Success Criteria
+
+- ✅ Existing BACKLOG.md content read successfully
+- ✅ Task section located by ID
+- ✅ Changes summary clearly describes what changed
+- ✅ Task section properly merged into BACKLOG.md
+- ✅ All other BACKLOG.md content preserved unchanged
+- ✅ Output is valid JSON with all required fields
+
+## Error Handling
+
+### Task Not Found
+
+If the task ID cannot be found in BACKLOG.md:
+
+```json
+{
+	"changes_summary": "# Error: Task Not Found\\n\\nTask [TASK-ID] was not found in BACKLOG.md.\\n\\nAvailable tasks: [list task IDs found]\\n",
+	"backlog_document": null,
+	"updated_task": null,
+	"error": "Task [TASK-ID] not found in BACKLOG.md"
+}
+```
+
+### BACKLOG.md Cannot Be Read
+
+If the file cannot be read:
+
+```json
+{
+	"changes_summary": "# Error: Cannot Read BACKLOG.md\\n\\nFile not found or not readable: [path]\\n",
+	"backlog_document": null,
+	"updated_task": null,
+	"error": "Cannot read BACKLOG.md at [path]"
+}
+```
+
+## Rules
+
+**DO**:
+
+- ✅ Read the actual BACKLOG.md file content using `read_file` tool
+- ✅ Preserve ALL content outside the target task EXACTLY as-is
+- ✅ Use the exact merge algorithm: BEFORE + UPDATED_TASK + AFTER
+- ✅ Add refinement metadata (Last Refined, Testability Score) to the task
+- ✅ Generate clear changes summary showing what was modified
+- ✅ Output complete merged document with full integrity
+
+**DON'T**:
+
+- ❌ NEVER modify any other task sections
+- ❌ NEVER remove or alter phase headings, summary tables, or metadata
+- ❌ NEVER reformat or restructure preserved content
+- ❌ NEVER output partial BACKLOG.md content
+- ❌ NEVER truncate or summarize the BACKLOG.md content
+- ❌ NEVER change whitespace, line breaks, or formatting outside the target task
+- ❌ NEVER skip the changes_summary field
+
+## REMINDER: Output Requirements
+
+**Output ONLY the JSON object. No markdown, no code blocks, no explanatory text. Start directly with `{` and end with `}`.**
+
+The `backlog_document` field must contain the COMPLETE BACKLOG.md with the refined task merged in.