Problem Analysis
Current Structure Issues
Core Concepts Section (Currently mixing WHY and HOW):
Core Concepts/
- Understanding LeanSpec (5 principles + mental models + mindset + beliefs - TOO MUCH)
- Writing Specs AI Can Execute (This is HOW, not core concept)
- When to Use (This is HOW - decision framework)
Working with AI Section (Redundant and misplaced):
Working with AI/
- index, setup, agents-md, best-practices, examples
- Overlaps with Getting Started
- Mixes foundational setup with advanced tips
Features vs Workflow (Artificial separation):
Features/ (templates, frontmatter, custom-fields, variables)
Workflow/ (board-stats, dependencies, validation)
- Both are "how to use LeanSpec features"
- Split creates confusion about where to find things
- Missing basic commands (create, update, list, search)
User Confusion Points
- What IS LeanSpec fundamentally? (positioning/philosophy buried in verbose content)
- Why should I use it? (positioning not clear upfront)
- How do I get started? (split between Getting Started and Working with AI)
- How do I use basic commands? (not clearly documented)
- What are advanced features? (scattered across Features and Workflow)