Vision Document
Overview
Structured command to help create vision documents by guiding through focused discovery phases and building each section systematically following our established feature development process.
Create a vision document following the established feature development process. First, read the feature development guide at @~/.local/share/dotfiles/ai/guides/feature-development-process.md to understand the vision document structure and approach.
Note: If the project has a local copy of the guide at @project/guides/feature-development-process.md, you may reference that instead for project-specific modifications.
IMPORTANT: Start by creating a TODO list to track the 5 phases of vision document creation. Mark the first phase as "in_progress" and others as "pending".
Vision Document Structure
Our vision documents are lean and focused - typically 100-150 lines, never more than 200. They flow from general to specific:
Required sections:
- Clear vision statement (one sentence)
- Table of contents (with links to all major sections)
- Problem (what's broken, who it affects, why it matters)
- Solution (how we'll solve it, core philosophy, key capabilities)
- User Needs (simple bullets by role - what they need to accomplish)
- Future Possibilities (brief overview with reference to separate future.md)
- Scope (concrete list of what v1 delivers and what's not included)
What does NOT belong in vision:
- Detailed business justifications or ROI calculations
- Deployment details (where/how it runs - that's spec territory)
- Technical implementation details (APIs, schemas, architecture - that's spec territory)
- Detailed user stories or acceptance criteria (that's requirements territory)
- Step-by-step workflows or process flows (that's requirements territory)
- Repetitive sections that restate the same information
Process: Work Through These 5 Phases Sequentially
Phase 1: Problem Discovery
Ask focused questions to understand:
- What specific problem are we solving?
- Who experiences this problem and how?
- What's the current painful/manual process?
- What are the consequences of not solving this?
ONE QUESTION AT A TIME - Wait for answers before proceeding. NO CORPORATE SPEAK - Keep language conversational and direct.
Phase 2: Solution Exploration
Ask about:
- How do we envision solving this at a high level?
- What's our core philosophy or approach?
- What are the 3-5 key capabilities we need?
- What makes this solution different/better?
Phase 3: User Needs Analysis
Use consolidated user roles at vision level:
- End Users (all user types)
- Admin Staff (consolidate all staff types - Staff, Administrators, Organization Admins)
- Product Team (if relevant)
Avoid fine-grained role distinctions - detailed role breakdown goes in requirements document.
For each consolidated role, ask ONLY:
- What do they need to accomplish with this feature?
STOP THERE. Don't ask about "current pain points" or "how success looks different" - that creates redundancy with the Problem section and belongs in requirements.
Phase 4: Future & Scope Discovery
Ask about:
- What nice-to-have features should we consider for future phases?
- What scope are we explicitly INCLUDING in v1? (get concrete details)
- What scope are we explicitly NOT including in v1?
Key: Get detailed, concrete information about what v1 will actually deliver - this becomes the bridge to requirements.
Phase 5: Document Generation
Before generating, ruthlessly eliminate redundancy:
- Does this section repeat information from another section?
- Is this section justifying something already obvious from the problem?
- Is this spec-level detail (deployment, technical architecture)?
- Is this requirements-level detail (detailed workflows, acceptance criteria)?
Then generate three documents:
1. vision.md - The lean, focused vision document:
- Create a clear one-sentence vision statement
- Generate a table of contents with links to all major sections
- Compile vision document with concrete scope section
- Flow from general (problems, solution) to specific (detailed scope)
- Follow "no corporate speak" principle throughout
- Reference future.md in the brief future possibilities section
- Keep total length under 150 lines - be ruthless about brevity
2. future.md - Detailed future enhancements:
- Create separate detailed future.md document with all future features
- Organize by phases (Phase 2, Phase 3, etc.)
- Include strategic future vision (if applicable)
3. discussion-summary.md - Living discussion summary document:
- Create a unified discussion summary that will accumulate across all phases
- Include "Vision Phase" section with all vision-related discussions
- Include placeholder sections for Requirements, Spec, and Plan phases
- Document architectural decisions made and their rationale in Key Decisions Log
- Capture technical feasibility discussions and implementation ideas
- Note any technical constraints or challenges identified
- Include open questions that should be addressed in requirements/spec
- Add Technical Context section with files referenced and related features
- Organize with clear sections and table of contents
- This document serves as institutional memory across the entire feature lifecycle
Key Principles
Flow from General to Specific: Start with high-level problems and solutions, end with concrete scope details that bridge naturally to requirements.
Scope Section is Critical: This should be a concrete LIST of what v1 delivers. Think: bullet points of capabilities/tools/features. This bridges vision to requirements.
BUT don't include:
- How it will be deployed (staging vs production) - that's spec territory
- Technical architecture details - that's spec territory
- Justifications for why things are excluded - just list what's out, no explanations needed
Separate Future Content: Create detailed future.md document for all future features. Vision should only have brief future overview.
No Corporate Speak: Write for humans first. Use clear, simple language. Avoid jargon and unnecessarily complex terminology.
User Role Consolidation: Keep user roles consolidated at vision level. Detailed role breakdowns belong in requirements.
Eliminate Redundancy (CRITICAL): We're a small team that values lean, readable documents. Every section must add NEW information. Before including a section, ask: "Does this repeat something already said?" If yes, DELETE IT.
Common redundant patterns to AVOID:
- "Business Case" that just restates the problem in corporate language
- "Consequences" section that repeats pain points already in Problem
- "Who This Affects" section when it's obvious from Problem
- Multiple sections listing benefits/value in different ways
- Detailed "current pain points" AND "how success looks different" in user needs (Problem section already covers this)
Keep It Short: Vision documents should be 100-150 lines MAX. If you're over 200 lines, you're repeating yourself or including spec/requirements-level detail.
Guidelines
- Ask ONE question at a time and wait for response
- Update your TODO list as you complete each phase
- Keep questions conversational, not corporate-speak
- Focus on immediately useful information, avoid fluff
- Reference any existing notes or context provided
- Stay practical - we're a small team that values readable, actionable documents
- During discovery, it's normal to discuss technical feasibility and architecture - capture all of this
- Always create three documents at the end: vision.md, future.md, and discussion-summary.md
Getting Started Process
- Create your 5-phase TODO list immediately
- Ask user: "What feature directory are you working in? Please provide the full path (e.g., project/features/FT033-feature-name)"
- Ask user: "If you have existing notes, please tag them with @notes.md or @[filename].md so I can review them"
- Validate the directory exists and confirm that's where you'll create vision.md, future.md, and discussion-summary.md
- Review any tagged notes files
- Begin Phase 1 with the first problem discovery question
- Keep questions focused and wait for answers before proceeding to next questions
- During conversations, capture technical/architectural discussions even if they don't directly go into vision.md
What to Capture in discussion-summary.md
This document should be structured to accumulate context across all feature development phases. For vision phase, create the full document structure:
Document Structure:
# Feature Name: Discussion Summary
Living document capturing technical discussions, research, decisions, and
context from all phases of feature development.
## Table of Contents
- [Vision Phase](#vision-phase)
- [Requirements Phase](#requirements-phase)
- [Spec Phase](#spec-phase)
- [Plan Phase](#plan-phase)
- [Key Decisions Log](#key-decisions-log)
- [Technical Context](#technical-context)
## Vision Phase
[Vision phase content goes here]
## Requirements Phase
*To be added during requirements phase.*
## Spec Phase
*To be added during spec phase.*
## Plan Phase
*To be added during plan phase.*
## Key Decisions Log
| # | Decision | Rationale | Phase |
|---|----------|-----------|-------|
[Decisions from vision phase]
## Technical Context
### Files Referenced
[Backend and frontend files referenced]
### Related Features
[Related feature references]Vision Phase Content to Include:
- Core problem identified and all nuances discussed
- Solution approach and how it evolved during discussion
- Technical feasibility discussions
- Architectural decisions made and their rationale
- Implementation ideas explored (even if not chosen)
- Technology choices and why (SDKs, frameworks, protocols)
- Technical constraints identified
- Integration points with existing systems
- Open questions for requirements/spec phases
Key Decisions Log:
- Number decisions starting from 1
- Include decision, rationale, and "Vision" as the phase
- Later phases will continue the numbering
Technical Context:
- List files referenced during discussions (backend and frontend paths)
- Note related features that may be affected
Purpose: This document serves as institutional memory across the entire feature lifecycle. Each phase adds its section, and the Key Decisions Log and Technical Context accumulate across all phases.