@windagency/valora 2.0.1

package/data/prompts/02_context/load-specifications.md

@@ -0,0 +1,354 @@
+---
+id: context.load-specifications
+version: 1.0.0
+category: context
+experimental: true
+name: Load Specifications
+description: Load and parse refined specifications from various sources
+tags:
+  - specifications
+  - requirements
+  - context-loading
+model_requirements:
+  min_context: 128000
+  recommended:
+    - gpt-5-thinking-high
+    - gpt-o1-high
+agents:
+  - product-manager
+dependencies:
+  requires:
+    - context.use-modern-cli-tools
+inputs:
+  - name: specs_file_arg
+    description: Optional path to specifications file
+    type: string
+    required: false
+outputs:
+  - specifications
+  - project_type
+  - existing_context
+tokens:
+  avg: 3000
+  max: 6000
+  min: 1500
+---
+
+# Load Specifications
+
+## Objective
+
+Load refined specifications from available sources and extract structured requirements data for PRD generation.
+
+## Instructions
+
+### Step 1: Locate Specifications
+
+Check for specifications in priority order:
+
+1. **User-provided file** (if file content is provided below):
+   - The file content is provided in the user message between `--- File: ... ---` markers
+   - Parse the provided content directly (do NOT attempt to read files yourself)
+   - Validate it contains specifications
+   - Use as primary source
+
+2. **Recent SPECS file** in `knowledge-base/`:
+   - Search for `SPECS-*.md` files
+   - Sort by timestamp (most recent first)
+   - Read most recent file
+
+3. **FUNCTIONAL.md** in `knowledge-base/`:
+   - Check for `knowledge-base/FUNCTIONAL.md`
+   - Use as fallback specifications source
+
+4. **Existing PRD.md** (for updates):
+   - Check for `knowledge-base/PRD.md`
+   - Extract requirements for update scenario
+
+5. **User-provided inline** (last resort):
+   - Ask user to provide specifications
+   - Guide them on required format
+
+### Step 2: Parse Specifications
+
+**Extract key sections**:
+
+- **Problem Statement**: What problem are we solving?
+- **Target Users**: Who will use this?
+- **Success Criteria**: How do we measure success?
+- **Functional Requirements**: What features are needed?
+  - Must Have (P0)
+  - Should Have (P1)
+  - Nice to Have (P2)
+- **Non-Functional Requirements**: Performance, security, scalability
+- **Constraints**: Technical, business, time, budget
+- **Out of Scope**: What we're NOT doing
+- **Assumptions**: What we're assuming to be true
+- **Open Questions**: Unresolved items
+- **Dependencies**: External systems, services, teams
+- **Risks**: Potential issues and mitigations
+
+**Parse format**:
+
+- Support markdown heading structure
+- Extract bullet points and checklists
+- Parse tables if present
+- Identify requirement IDs (FR-001, NFR-002, etc.)
+- Extract priority markers (P0, P1, P2)
+
+### Step 3: Determine Project Type
+
+Analyze specifications to identify project type:
+
+**Types**:
+
+1. **Greenfield**: New project from scratch
+   - Indicators: No existing codebase mentioned, "build new", "start fresh"
+   - Implications: Need full architecture, all components new
+
+2. **Brownfield**: Extending existing system
+   - Indicators: References to existing code, "add to", "extend"
+   - Implications: Integration with existing architecture, backward compatibility
+
+3. **Migration**: Replacing/modernizing legacy
+   - Indicators: "migrate from", "replace", "modernize"
+   - Implications: Data migration, parallel run, cutover strategy
+
+4. **Integration**: Connecting multiple systems
+   - Indicators: "integrate with", "connect", "sync between"
+   - Implications: API contracts, data mapping, error handling
+
+5. **Enhancement**: Adding features to stable product
+   - Indicators: "add feature", "improve", specific feature name
+   - Implications: Minimal disruption, feature flags, incremental rollout
+
+**Decision logic**:
+
+- Greenfield if: No codebase references + "new" keywords
+- Brownfield if: Existing code references + "add/extend" keywords
+- Migration if: "migrate/replace" keywords + old/new system mentions
+- Integration if: Multiple system names + "integrate/connect" keywords
+- Enhancement if: Specific feature additions + stable product context
+
+### Step 4: Load Existing Project Context
+
+Check for existing documentation in `knowledge-base/`:
+
+**Architecture documentation**:
+
+- `knowledge-base/infrastructure/HLD.md` (High-Level Design)
+- `knowledge-base/backend/ARCHITECTURE.md`
+- `knowledge-base/frontend/ARCHITECTURE.md`
+
+**Technical specifications**:
+
+- `knowledge-base/backend/API.md` (API contracts)
+- `knowledge-base/backend/DATA.md` (Data models)
+- `knowledge-base/frontend/COMPONENTS.md`
+
+**Testing & deployment**:
+
+- `knowledge-base/*/TESTING.md`
+- `infrastructure/` (deployment configs)
+
+**Parse existing context**:
+
+- Current tech stack
+- Architectural patterns (microservices, monolith, etc.)
+- Integration points
+- Deployment environment (cloud provider, k8s, etc.)
+- Testing strategies
+
+### Step 5: Extract Tech Stack & Constraints
+
+**From specifications**:
+
+- Explicit technology mentions (React, Node.js, PostgreSQL, etc.)
+- Platform constraints (mobile, web, desktop)
+- Infrastructure requirements (AWS, Azure, on-prem)
+
+**From existing context**:
+
+- Current languages and frameworks
+- Database systems in use
+- CI/CD pipelines
+- Monitoring and logging tools
+
+**From constraints section**:
+
+- Technical debt limitations
+- Performance requirements
+- Security standards
+- Compliance requirements (GDPR, HIPAA, SOC2)
+
+### Step 6: Validate Completeness
+
+Check if specifications are sufficient for PRD generation:
+
+**Required elements** (must have):
+
+- [ ] Problem statement is clear
+- [ ] Target users are identified
+- [ ] At least 3 P0 requirements defined
+- [ ] Success criteria are measurable
+- [ ] Constraints are documented
+
+**Warning elements** (should have):
+
+- [ ] Non-functional requirements specified
+- [ ] Dependencies identified
+- [ ] Risks documented
+- [ ] Out-of-scope items listed
+
+**Completeness score**:
+
+```plaintext
+Completeness = (Required elements / 5 + Warning elements / 4) / 2 * 100%
+```
+
+**Decision**:
+
+- **≥ 80%**: Sufficient for PRD generation
+- **60-79%**: Proceed with warnings
+- **< 60%**: Insufficient, request more details
+
+## Output Format
+
+**CRITICAL: Your response MUST be ONLY valid JSON. No markdown, no explanations, no prose. Just the JSON object below.**
+
+```json
+{
+	"specifications": {
+		"source": "knowledge-base/SPECS-20251113-143022.md",
+		"problem_statement": "Teams struggle with task visibility...",
+		"target_users": {
+			"primary": "Remote team leads (10-50 person teams)",
+			"secondary": "Individual contributors",
+			"personas": ["Team Lead", "Developer", "QA"]
+		},
+		"success_criteria": {
+			"quantitative": [
+				{ "metric": "User adoption", "target": "80% within 3 months" },
+				{ "metric": "Status meetings reduction", "target": "30%" }
+			],
+			"qualitative": ["Improved task visibility", "Better accountability"]
+		},
+		"functional_requirements": {
+			"p0": [
+				{ "id": "FR-001", "description": "Create and assign tasks" },
+				{ "id": "FR-002", "description": "Real-time status updates" }
+			],
+			"p1": [{ "id": "FR-003", "description": "Slack/Teams integration" }],
+			"p2": [{ "id": "FR-004", "description": "Gantt chart view" }]
+		},
+		"non_functional_requirements": [
+			{ "id": "NFR-001", "category": "Performance", "description": "<2s page load" },
+			{ "id": "NFR-002", "category": "Security", "description": "OAuth2 + RBAC" },
+			{ "id": "NFR-003", "category": "Scalability", "description": "Support 10k users" }
+		],
+		"constraints": {
+			"technical": ["Must use existing PostgreSQL database"],
+			"business": ["Budget: $50k"],
+			"time": ["Launch by Q2 2026"],
+			"regulatory": ["GDPR compliant"]
+		},
+		"out_of_scope": ["Mobile app (Phase 2)", "Advanced analytics dashboard"],
+		"assumptions": ["Users have modern browsers (Chrome, Firefox, Safari)", "Team sizes are 10-50 people"],
+		"open_questions": [
+			{ "question": "Support offline mode?", "priority": "medium" },
+			{ "question": "Integration with Jira?", "priority": "low" }
+		],
+		"dependencies": [
+			{ "name": "Slack API", "type": "external", "criticality": "high" },
+			{ "name": "Auth service", "type": "internal", "criticality": "high" }
+		],
+		"risks": [
+			{
+				"description": "Slack API rate limits",
+				"impact": "high",
+				"likelihood": "medium",
+				"mitigation": "Implement caching and batching"
+			}
+		]
+	},
+	"project_type": "brownfield",
+	"project_type_reasoning": "Extending existing task management system with real-time features",
+	"existing_context": {
+		"has_architecture_docs": true,
+		"tech_stack": {
+			"frontend": ["React", "TypeScript"],
+			"backend": ["Node.js", "Express"],
+			"database": ["PostgreSQL"],
+			"infrastructure": ["AWS", "Docker", "Kubernetes"]
+		},
+		"deployment_environment": "AWS EKS",
+		"testing_strategy": "Jest + Cypress"
+	},
+	"completeness_score": 0.92,
+	"completeness_status": "sufficient",
+	"missing_elements": ["Performance benchmarks not specified"],
+	"ready_for_prd": true
+}
+```
+
+## Success Criteria
+
+- ✅ Specifications loaded from appropriate source
+- ✅ All key sections extracted
+- ✅ Project type identified
+- ✅ Existing context analyzed
+- ✅ Completeness validated (≥80%)
+- ✅ Structured data ready for PRD generation
+
+## Error Handling
+
+### No Specifications Found
+
+**Issue**: Cannot locate specifications file
+
+**Action**:
+
+1. List available files in knowledge-base/
+2. Ask user to provide specifications
+3. Suggest running `/refine-specs` first
+4. Provide specifications template
+
+### Malformed Specifications
+
+**Issue**: Specifications file doesn't parse correctly
+
+**Action**:
+
+1. Attempt partial parsing
+2. Extract what's available
+3. Warn user about missing sections
+4. Suggest manual review
+
+### Insufficient Specifications
+
+**Issue**: Completeness score < 60%
+
+**Action**:
+
+1. List missing required elements
+2. Request specific information
+3. Suggest re-running `/refine-specs`
+4. Don't proceed to PRD generation
+
+### Conflicting Information
+
+**Issue**: Specifications contradict existing context
+
+**Action**:
+
+1. Highlight conflicts
+2. Ask user to clarify intent
+3. Document resolution
+4. Update specifications if needed
+
+## Notes
+
+- This prompt focuses on LOADING and PARSING, not generating
+- Validation is lightweight (completeness check only)
+- Deep analysis happens in next stage (analyze-requirements)
+- Structure output for easy consumption by subsequent prompts

package/data/prompts/02_context/load-task.md

@@ -0,0 +1,311 @@
+---
+id: context.load-task
+version: 1.0.0
+category: context
+experimental: true
+name: Load Task
+description: Load task details from TODO.md or BACKLOG.md for refinement
+tags:
+  - task-loading
+  - context
+  - task-details
+model_requirements:
+  min_context: 128000
+  recommended:
+    - claude-haiku-4.5
+agents:
+  - product-manager
+dependencies:
+  requires:
+    - context.use-modern-cli-tools
+inputs:
+  - name: task_id
+    description: Optional explicit task ID parameter
+    type: string
+    required: false
+  - name: backlog_file
+    description: Path to BACKLOG.md file (defaults to knowledge-base/BACKLOG.md)
+    type: string
+    required: false
+    default: knowledge-base/BACKLOG.md
+outputs:
+  - task_details
+  - current_acceptance_criteria
+  - linked_requirements
+tokens:
+  avg: 2000
+  max: 4000
+  min: 1000
+---
+
+# Load Task
+
+## 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
+
+Retrieve task details and related context from TODO.md or BACKLOG.md for the refinement process.
+
+## Task Source Priority
+
+```plaintext
+1. Explicit task ID via --task-id parameter (search in backlog_file)
+2. Most recent task from TODO.md (marked "In Progress" or "Ready")
+3. Task reference from backlog_file (defaults to knowledge-base/BACKLOG.md)
+4. User-provided inline description
+```
+
+## Instructions
+
+### Step 1: Identify Task Source
+
+**Backlog file location**: Use `backlog_file` parameter if provided, otherwise default to `knowledge-base/BACKLOG.md`.
+
+**If `task_id` provided**:
+
+- Search the backlog file for exact task ID match
+- Search TODO.md for task reference
+- Extract full task entry
+- Validate task exists and is not completed
+
+**If no `task_id` provided**:
+
+- Check TODO.md for most recent fetched task
+- Look for task marked "In Progress" or "Ready"
+- Use most recently modified task entry
+- If multiple candidates, select highest priority
+
+**If inline description**:
+
+- Treat as new task specification
+- Extract key requirements from description
+- Note: May need to add to backlog later
+
+### Step 2: Extract Task Components
+
+Parse and extract all available task information:
+
+```plaintext
+Required fields:
+- Task ID (if exists)
+- Task title
+- Description/requirements
+- Priority level (P0/P1/P2)
+- Domain (frontend/backend/infra/data/testing/documentation)
+
+Optional fields:
+- Acceptance criteria
+- Effort estimate (XS/S/M/L/XL)
+- Dependencies (task IDs)
+- Linked PRD requirements (FR-XXX, NFR-XXX, US-XXX)
+- Constraints/considerations
+- Technical notes
+- Testing requirements
+```
+
+### Step 3: Load Related Context
+
+**PRD Requirements**:
+
+- If task references FR-XXX, NFR-XXX, or US-XXX requirements
+- Load from knowledge-base/PRD.md
+- Extract full requirement text and acceptance criteria
+
+**Architecture Context**:
+
+- Based on task domain, identify relevant architecture docs
+- Frontend tasks → knowledge-base/frontend/ARCHITECTURE.md
+- Backend tasks → knowledge-base/backend/ARCHITECTURE.md
+- Data tasks → knowledge-base/backend/DATA.md
+
+**Similar Implementations**:
+
+- Search for tasks with similar descriptions in BACKLOG.md
+- Identify completed tasks in same domain
+- Extract patterns and lessons learned
+
+**Dependencies**:
+
+- If task lists dependency task IDs
+- Load dependency task details
+- Check completion status of dependencies
+
+### Step 4: Extract Current Acceptance Criteria
+
+**If task has explicit acceptance criteria**:
+
+- Extract all listed criteria
+- Parse format (checklist, Given-When-Then, etc.)
+- Categorize by type (functional, non-functional, edge cases)
+
+**If task lacks acceptance criteria**:
+
+- Note as gap for refinement
+- Check if linked PRD requirements have criteria
+- Flag for creation in refinement stage
+
+### Step 5: Assess Initial State
+
+Quick assessment of task clarity:
+
+**Check for presence of**:
+
+- [ ] Clear description
+- [ ] Defined scope
+- [ ] Acceptance criteria (any)
+- [ ] Priority assigned
+- [ ] Domain identified
+- [ ] Dependencies noted (if any)
+
+**Initial clarity indicators**:
+
+- All checked → High clarity baseline
+- 4-5 checked → Moderate clarity baseline
+- <4 checked → Low clarity baseline
+
+## Output Format
+
+**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
+{
+	"task_details": {
+		"id": "FE0012",
+		"title": "Add search to user dashboard",
+		"description": "Users need search functionality to find transactions quickly",
+		"priority": "P1",
+		"domain": "Frontend",
+		"effort": "M",
+		"effort_estimate": "3-4 days",
+		"phase": 2,
+		"status": "ready",
+		"source": "BACKLOG.md",
+		"dependencies": [],
+		"linked_requirements": ["FR-023", "US-023-1"],
+		"constraints": ["Must work on mobile devices"],
+		"technical_notes": "Consider using existing search component pattern"
+	},
+	"current_acceptance_criteria": ["Users can search transactions", "Search updates in real-time"],
+	"linked_requirements": {
+		"FR-023": {
+			"title": "Transaction Search",
+			"description": "Enable users to search transaction history by multiple criteria",
+			"acceptance_criteria": [
+				"Search by description (partial match)",
+				"Search by amount (exact or range)",
+				"Search by date (range)",
+				"Results appear within 500ms"
+			]
+		},
+		"US-023-1": {
+			"story": "As a user, I want to search my transactions by description, so that I can quickly find specific purchases",
+			"acceptance_criteria": [
+				"GIVEN I am on the dashboard",
+				"WHEN I type in the search field",
+				"THEN transactions matching my query appear in real-time"
+			]
+		}
+	},
+	"related_context": {
+		"architecture_docs": ["knowledge-base/frontend/ARCHITECTURE.md"],
+		"similar_tasks": [
+			{
+				"id": "FE0008",
+				"title": "Admin search functionality",
+				"status": "completed",
+				"lessons": "Used debounce hook, 300ms delay worked well"
+			}
+		],
+		"patterns": [
+			"Use useDebounce hook for search input",
+			"Follow SearchInput component pattern",
+			"API endpoint pattern: GET /api/{resource}?search="
+		]
+	},
+	"initial_assessment": {
+		"clarity_baseline": "moderate",
+		"has_description": true,
+		"has_scope": true,
+		"has_acceptance_criteria": true,
+		"has_priority": true,
+		"has_domain": true,
+		"has_dependencies_noted": true,
+		"checked_count": 6,
+		"gaps_identified": [
+			"Acceptance criteria are vague",
+			"Missing edge case coverage",
+			"No performance targets specified in task"
+		]
+	}
+}
+```
+
+## Success Criteria
+
+- ✅ Task successfully located and loaded
+- ✅ All available task metadata extracted
+- ✅ Linked PRD requirements loaded (if applicable)
+- ✅ Related context identified
+- ✅ Current acceptance criteria extracted or noted as missing
+- ✅ Initial clarity assessment completed
+- ✅ Dependencies validated
+
+## Error Handling
+
+### Task Not Found
+
+**If task_id provided but not found**:
+
+- Search in completed tasks section
+- If completed: Return completion details with warning
+- If truly missing: List available tasks, suggest alternatives
+- Error: "Task {task_id} not found in BACKLOG.md or TODO.md"
+
+### Ambiguous Task
+
+**If multiple tasks match criteria**:
+
+- List all matching tasks
+- Request user clarification
+- Provide selection guidance (newest, highest priority)
+
+### Missing Context
+
+**If linked requirements not found**:
+
+- Note as missing in output
+- Proceed with available information
+- Flag for clarification in refinement stage
+
+## Rules
+
+**DO**:
+
+- ✅ Check multiple sources (TODO.md, BACKLOG.md, PRD.md)
+- ✅ Extract all available context
+- ✅ Note gaps explicitly
+- ✅ Load related requirements and patterns
+- ✅ Validate task exists before proceeding
+
+**DON'T**:
+
+- ❌ Don't assume task structure - handle various formats
+- ❌ Don't fail if some fields missing - extract what's available
+- ❌ Don't skip related context - it aids refinement
+- ❌ Don't modify task data - load as-is
+
+## Notes
+
+- This prompt loads context only - no analysis or refinement
+- Task may be in various formats - be flexible in parsing
+- Initial assessment is quick scan, not full analysis
+- Related context helps inform later refinement stages
+- Output feeds directly into clarity analysis stage
+
+## REMINDER: Output Requirements
+
+**Output ONLY the JSON object. No markdown, no code blocks, no explanatory text. Start directly with `{` and end with `}`.**