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
• Requirements Phase
• Spec Phase
• Plan Phase
• Key Decisions Log
• 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

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.