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.

feature-vision