| name | vision |
| description | Parses and analyzes project vision to extract structured requirements. Use at project start to understand goals, scope, and constraints. Triggers on: analyze vision, parse project goals, understand requirements. |
Vision Analysis Skill
Parse the project vision document and extract structured requirements for architecture and planning.
Workspace Mode Note
When running in workspace mode, all paths are relative to .aha-loop/ directory:
- Vision file:
.aha-loop/project.vision.md
- Analysis output:
.aha-loop/project.vision-analysis.md
The orchestrator will provide the actual paths in the prompt context.
The Job
- Read
project.vision.md from the project root
- Validate all required sections are present
- Extract and structure the requirements
- Identify project type and scale
- Output analysis to guide architecture decisions
- Save analysis to
project.vision-analysis.md
Input: project.vision.md
The vision document should contain:
Required Sections
| Section | Purpose |
|---|
| What | One-sentence description of the project |
| Why | Motivation and problem being solved |
| Target Users | Who will use this product |
| Success Criteria | Measurable definition of success |
Optional Sections
| Section | Purpose |
|---|
| Constraints | Technical, budget, or time limitations |
| Inspirations | Reference products or desired style |
| Non-Goals | What the project explicitly won't do |
Analysis Process
Step 1: Validate Vision Document
Check that project.vision.md exists and contains required sections:
## Validation Checklist
- [ ] What section present and clear
- [ ] Why section explains motivation
- [ ] Target Users defined
- [ ] Success Criteria are measurable
If sections are missing or unclear, document what's needed before proceeding.
Step 2: Identify Project Type
Classify the project:
| Type | Characteristics |
|---|
| CLI Tool | Command-line interface, no UI |
| Web App | Browser-based, frontend + backend |
| API Service | Backend only, REST/GraphQL |
| Library | Reusable code package |
| Desktop App | Native desktop application |
| Mobile App | iOS/Android application |
| Full Stack | Complete web application |
| Infrastructure | DevOps, deployment tools |
Step 3: Estimate Project Scale
| Scale | Stories | Duration | Complexity |
|---|
| Small | 5-15 | Days | Single component |
| Medium | 15-50 | Weeks | Multiple components |
| Large | 50-200 | Months | Full system |
| Enterprise | 200+ | Quarters | Multiple systems |
Step 4: Extract Core Features
From the vision, identify:
- Must-Have Features - Critical for MVP
- Should-Have Features - Important but not blocking
- Nice-to-Have Features - Enhancements for later
- Out of Scope - Explicitly excluded
Step 5: Identify Technical Implications
Based on features, note:
- Data storage needs (database type, scale)
- Authentication requirements
- External integrations
- Performance requirements
- Security considerations
- Deployment environment
Output: project.vision-analysis.md
# Vision Analysis
**Generated:** [timestamp]
**Vision Version:** [hash or date of vision.md]
## Project Classification
- **Type:** [Web App | API Service | CLI Tool | ...]
- **Scale:** [Small | Medium | Large | Enterprise]
- **Estimated Stories:** [range]
## Core Requirements
### Must-Have (MVP)
1. [Feature 1]
2. [Feature 2]
3. ...
### Should-Have (Post-MVP)
1. [Feature 1]
2. ...
### Nice-to-Have (Future)
1. [Feature 1]
2. ...
### Out of Scope
- [Excluded item 1]
- [Excluded item 2]
## Technical Implications
### Data & Storage
- [Storage needs analysis]
### Authentication & Security
- [Auth requirements]
### Integrations
- [External system integrations]
### Performance
- [Performance requirements]
### Deployment
- [Deployment environment needs]
## Constraints Summary
| Constraint | Impact |
|------------|--------|
| [Constraint 1] | [How it affects decisions] |
## Open Questions
- [ ] [Question that needs clarification]
- [ ] [Another question]
## Recommended Next Steps
1. Run Architect Skill to determine technology stack
2. Address any open questions before proceeding
3. ...
## Architecture Hints
Based on this vision, consider:
- [Hint about architecture approach]
- [Hint about technology category]
Decision Points
When Vision is Unclear
If the vision document lacks detail:
- Do NOT guess - Document what's missing
- List specific questions - What exactly needs clarification
- Provide options - Suggest possible interpretations
- Proceed cautiously - Make conservative assumptions and note them
When Scope is Too Large
If estimated scale is "Large" or "Enterprise":
- Recommend phased approach - Break into multiple major milestones
- Identify MVP subset - What's the smallest useful version
- Flag risk - Note that large projects need careful management
When Constraints Conflict
If constraints seem to conflict with goals:
- Document the conflict - Be explicit about the tension
- Propose resolutions - Suggest possible compromises
- Prioritize - Recommend which constraint to relax
Integration with Orchestrator
After vision analysis:
- Save
project.vision-analysis.md to project root
- Signal completion to orchestrator
- Architect Skill uses this analysis as input
Example Analysis
Input Vision:
# Project Vision
## What
A personal finance tracker that helps users manage their budget and track expenses.
## Why
Existing apps are too complex. Users need a simple, focused tool.
## Target Users
Individuals who want basic expense tracking without complexity.
## Success Criteria
- Users can add expenses in under 5 seconds
- Monthly reports generated automatically
- Works offline
## Constraints
- Must be a web app (PWA for offline)
- No paid APIs (keep it free)
- Single developer, limited time
Output Analysis:
# Vision Analysis
## Project Classification
- **Type:** Web App (PWA)
- **Scale:** Medium
- **Estimated Stories:** 20-35
## Core Requirements
### Must-Have (MVP)
1. Quick expense entry (< 5 seconds)
2. Expense categorization
3. Monthly report generation
4. Offline support (PWA)
5. Data persistence
### Should-Have (Post-MVP)
1. Budget setting and tracking
2. Expense trends visualization
3. Export functionality
### Nice-to-Have (Future)
1. Multiple currencies
2. Receipt photo capture
3. Bank import
### Out of Scope
- Multi-user/sharing features
- Investment tracking
- Tax preparation
## Technical Implications
### Data & Storage
- Local-first (IndexedDB for offline)
- Optional cloud sync later
### Authentication & Security
- Initially: None (local only)
- Later: Simple auth for sync
### Performance
- Critical: Fast expense entry
- PWA service worker for offline
### Deployment
- Static hosting (Netlify, Vercel)
- No backend initially
## Constraints Summary
| Constraint | Impact |
|------------|--------|
| PWA required | Must use service workers, IndexedDB |
| No paid APIs | Use free/open solutions only |
| Limited time | Focus on MVP, defer nice-to-haves |
## Recommended Next Steps
1. Run Architect Skill to select frontend framework
2. Design offline-first data architecture
3. Plan PWA implementation strategy
Checklist
Before completing vision analysis:
