Documentation Separation Guidelines¶

Version: 1.0 Status: Active Standard Last Updated: 2025-01-11

Purpose¶

Ensure clear separation between MVP and Vision documentation to prevent scope creep and maintain team focus.

Visual Indicators¶

Document Headers¶

MVP Documents:

# Feature Name

**Scope**: MVP
**Timeline**: Weeks 1-12
**Status**: Building Now

Vision Documents:

# [VISION - Not MVP] Feature Name

**Timeline**: Post-MVP, triggered by [specific metrics]
**Current Status**: Concept only
**Warning**: Do not implement during MVP phase

In-Line Tags¶

Use these tags throughout documentation:

[MVP] - Include in current build
[VISION] - Future capability
[BLOCKED] - Waiting on external dependency
[RESEARCH] - Needs investigation

Directory Indicators¶

/docs-internal/docs/
├── 03-business/           # Mixed content (use tags)
├── 04-architecture/       # Mixed content (use tags)
├── 05-features/          # MVP features only
├── 07-vision/            # Vision features only
    ├── index.md          # Big warning about vision status
    └── [subdirectories]  # Clearly future-state

Content Rules¶

MVP Documentation Must:¶

Be buildable in 8-12 weeks
Work with 3-person team
Use existing technologies
Have clear success metrics
Fit within 3 pages

Vision Documentation Must:¶

Start with [VISION - Not MVP]
Include evolution triggers
Explain why it's not MVP
Reference MVP prerequisites
Stay in ../08-vision/ directory

Migration Checklist¶

When reviewing existing docs:

Contains ML/AI sophistication? → Move to Vision
Requires > 3 months to build? → Move to Vision
Needs team > 3 people? → Move to Vision
No clear customer demand? → Move to Vision
Depends on future features? → Move to Vision

Examples¶

Good MVP Documentation¶

# Policy Upload Workflow

**Scope**: MVP
**Timeline**: Week 3-4
**Status**: Building Now

Users can upload existing policies (PDF/Word) and we'll extract text and identify variables for replacement.

## Implementation

- Use pdf-parse for PDF extraction
- Simple variable detection with regex
- Store as Markdown in Supabase

Good Vision Documentation¶

# [VISION - Not MVP] AI Policy Generation

**Timeline**: Post-MVP, after 100+ policies uploaded
**Current Status**: Concept only
**Warning**: Do not implement during MVP phase

## Concept

Use LLM to generate custom policies based on:

- Industry patterns
- Existing policy analysis
- Regulatory requirements

## Evolution Trigger

Implement when:

- 100+ policies in system
- Clear patterns identified
- Legal review completed

File Naming Conventions¶

MVP Files¶

feature-name.md
implementation-guide.md
mvp-architecture.md

Vision Files¶

vision-feature-name.md
future-capability.md
Always in ../08-vision/ directory

Cross-References¶

From MVP to Vision¶

See Future Enhancements in the vision directory for post-MVP capabilities.

From Vision to MVP¶

Requires MVP Feature as prerequisite.

Review Process¶

Before merging any documentation:

Check Scope: Is this MVP or Vision?
Verify Location: Is it in the right directory?
Confirm Tags: Are visual indicators present?
Validate Timeline: Can we build this now?
Test Triggers: Are evolution criteria clear?

Common Mistakes¶

❌ Mixing MVP and Vision¶

"The system uses simple rules initially but will use ML to..."

✅ Clear Separation¶

"The MVP uses simple rules. See [Vision: ML Enhancement] for future capabilities."

❌ Vague Timeline¶

"We'll add this later"

✅ Specific Triggers¶

"Add after 50+ customers actively using feature"

❌ Assuming Resources¶

"The AI team will handle this"

✅ Reality Check¶

"Requires hiring ML engineer (post-funding)"

Enforcement¶

PR Reviews: Check for proper separation
Automated Checks: Script to verify tags
Team Training: Regular reminders
Documentation Audits: Quarterly review

Remember¶

Clear separation helps everyone:

Developers: Know what to build now
Sales: Set correct expectations
Investors: See disciplined approach
Team: Stay focused on MVP

"If in doubt, it's probably Vision."