@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/048-spec-complexity-analysis/FINDINGS.md

@@ -0,0 +1,113 @@
+# Problem Analysis: Spec Complexity
+
+> Part of spec: [048-spec-complexity-analysis](README.md)
+
+## Symptoms of Over-Complexity
+
+### 1. Corruption Issues
+- Spec 018 had major corruption: duplicate sections, malformed code blocks, incomplete JSON
+- This is the 3rd+ time we've encountered spec corruption
+- Root cause: Complex multi-edit operations on large files with interleaved code/text
+- **The tool struggles with its own specs**
+
+### 2. Context Window Issues
+- 591 lines = ~15,000-20,000 tokens
+- AI agents must load entire spec to make any edit
+- Risk of missing context or creating inconsistencies
+- Exactly the problem we're solving for users!
+
+### 3. Maintenance Burden
+- Updates require careful coordination across many sections
+- Easy to update one part and miss related sections
+- Testing section disconnected from implementation plan
+- Design decisions buried in implementation details
+
+### 4. Cognitive Overload
+- Hard to get "at a glance" understanding
+- Must scroll through multiple screenfuls to find specific info
+- Mixed concerns: philosophy, design, implementation, testing, configuration, examples
+- Violates "clarity over documentation" principle
+
+## Root Causes
+
+### Why are our specs growing?
+
+1. **Feature Complexity**: Some features genuinely are complex (spec 018 is comprehensive checking system)
+2. **Over-Documentation**: Including every possible use case, edge case, example
+3. **Mixed Concerns**: Design + implementation + testing + config + examples all in one file
+4. **Lack of Structure**: No clear stopping point or guideline for "too much"
+5. **Completeness Bias**: Feeling like we need to document everything upfront
+6. **No Enforcement**: No tooling to detect when specs get too large
+
+### Comparison to Our Philosophy
+
+| Principle | What We Say | What We Do |
+|-----------|-------------|------------|
+| "Write only what matters" | ✅ | ❌ 591 lines with exhaustive examples |
+| "If it doesn't add clarity, cut it" | ✅ | ❌ Keep adding sections for completeness |
+| "Lightweight SDD" | ✅ | ❌ 1,166-line spec is heavyweight |
+| "Clear enough for AI" | ✅ | ❌ AI corrupts our own specs |
+| "Lean enough to maintain" | ✅ | ❌ Maintenance is becoming painful |
+
+## What Makes a Spec "Too Complex"?
+
+### Quantitative Signals
+- **>400 lines**: High risk of becoming unwieldy
+- **>600 lines**: Almost certainly too complex
+- **>50 sections**: Too much to navigate mentally
+- **>10 code blocks**: Mixing too much code with prose
+- **Multiple corruption incidents**: Clear sign of tool limitations
+
+### Qualitative Signals
+- Multiple concerns mixed together (design + config + testing + examples)
+- Can't summarize in 1-2 paragraphs what the spec is about
+- Implementation plan has >6 phases
+- Reading through it takes >10 minutes
+- Updates frequently cause inconsistencies
+- AI agents struggle to edit it reliably
+
+### The Context Window Math
+
+```
+Average spec size:
+- Spec 018: 591 lines ≈ 15,000 tokens
+- Spec 045: 1,166 lines ≈ 30,000 tokens
+- Spec 043: 408 lines ≈ 10,000 tokens
+
+Claude Sonnet context: 200K tokens
+  - But loses quality after ~50K tokens of active context
+  - Working memory effectively ~20K-30K tokens
+
+Spec 045 = 30K tokens = entire working memory for ONE spec
+  - No room for code context, other specs, codebase understanding
+```
+
+## The Paradox: We Already Solved This!
+
+**We have the solution but aren't using it**:
+
+### Spec 012: Sub-Spec Files (Status: ✅ Complete, **never actually used**)
+
+We built this exact feature:
+```
+specs/048-spec-complexity-analysis/
+├── README.md           # Main spec (overview, decision)
+├── DESIGN.md          # Detailed design
+├── IMPLEMENTATION.md  # Implementation plan
+├── TESTING.md         # Test strategy
+└── EXAMPLES.md        # Code examples and configs
+```
+
+Why didn't we use it?
+- Forgot it exists?
+- Doesn't feel necessary until it's too late?
+- No tooling reminder when specs get large?
+- Cultural inertia toward single-file specs?
+- **Not dogfooding our own solution**
+
+### We're experiencing the exact problem we're solving
+
+1. ✅ We correctly identified: "30-page documents blow up AI's context window"
+2. ✅ We built tooling: Sub-spec files (spec 012) to split large docs
+3. ❌ We didn't use it: All our specs are still single large files
+4. ❌ We're hitting the limit: Corruption, maintenance burden, cognitive overload

package/.next/standalone/packages/ui/dist/standalone/specs/048-spec-complexity-analysis/GUIDELINES.md

@@ -0,0 +1,237 @@
+# Guidelines: When to Split Specs
+
+> Part of spec: [048-spec-complexity-analysis](README.md)
+
+## Line Count Thresholds
+
+- **<300 lines**: ✅ Ideal, keep as single file
+- **300-400 lines**: ⚠️ Warning zone, consider simplifying or splitting
+- **>400 lines**: 🔴 Strong candidate for splitting
+- **>600 lines**: 🔴 Almost certainly should be split
+
+## Complexity Signals
+
+- **>6 implementation phases**: Consider IMPLEMENTATION.md
+- **>10 code blocks**: Consider EXAMPLES.md or CONFIGURATION.md
+- **>40 sections**: Too much cognitive load
+- **Multiple corruption incidents**: Technical debt signal
+
+## Decision Tree: When to Split
+
+```
+Is the spec over 300 lines?
+├─ No → Keep as single file ✅
+└─ Yes → Does it have multiple distinct concerns?
+    ├─ No → Consider refactoring to be more concise
+    └─ Yes → Does each concern need deep detail?
+        ├─ No → Keep as single file, but trim content
+        └─ Yes → Split into sub-specs
+            ├── README.md (overview + decision)
+            ├── DESIGN.md (detailed design)
+            ├── IMPLEMENTATION.md (plan)
+            ├── TESTING.md (test strategy)
+            └── {CONCERN}.md (specific concerns)
+```
+
+## Distinct Concerns (Worthy of Split)
+
+### Worthy of separate file:
+- Detailed configuration (JSON schemas, examples >50 lines)
+- Extensive test strategy (beyond simple checklist)
+- Multi-phase implementation (>6 phases)
+- Code examples and patterns (>50 lines of code)
+- Architecture decisions (ADR-style documentation)
+- Migration strategy (from old to new approach)
+- API specifications (endpoints, schemas, validation)
+
+### Not worthy of separate file:
+- Simple plan with 3-4 steps
+- Basic testing checklist
+- Short code snippets (<20 lines)
+- Overview and design that fit together naturally
+
+## Progressive Disclosure Stages
+
+### Stage 1: Single File (Most Specs - <300 lines)
+- Use standard template
+- Keep under ~300 lines
+- If it fits comfortably, don't split
+
+### Stage 2: Growing Complexity (Some Specs - 300-400 lines)
+- Approaching complexity threshold
+- Multiple distinct concerns emerging
+- Consider splitting, but don't force it
+
+### Stage 3: Complex Feature (Few Specs - >400 lines)
+- Over 400 lines or multiple major concerns
+- Use sub-spec files (spec 012)
+- Split by concern, not arbitrarily
+
+### Stage 4: Epic/Multi-Phase (Rare - >600 lines)
+- Multi-month initiative
+- Consider whether it should be multiple specs instead
+- Or use sub-specs with phase-based breakdown
+
+## Case Study: How to Split Spec 018
+
+**Current state**: 591 lines, 43 sections, multiple concerns mixed
+
+**Proposed split**:
+
+```
+specs/018-spec-validation/
+├── README.md              # Overview, decision, summary (150 lines)
+│   ├─ Overview: Problem statement, goals
+│   ├─ Design: High-level approach (unified `check` command)
+│   ├─ Decision: Why expand `check` vs new `validate`
+│   └─ Links to sub-specs for details
+│
+├── VALIDATION-RULES.md   # What gets validated (150 lines)
+│   ├─ Frontmatter rules
+│   ├─ Structure rules
+│   ├─ Content rules
+│   ├─ Corruption detection rules
+│   └─ Staleness rules
+│
+├── CLI-DESIGN.md         # Command interface (100 lines)
+│   ├─ Command syntax
+│   ├─ Flags and options
+│   ├─ Output formats
+│   └─ Backwards compatibility
+│
+├── CONFIGURATION.md      # Config with examples (100 lines)
+│   ├─ Config schema
+│   ├─ JSON examples
+│   └─ Rule customization
+│
+├── IMPLEMENTATION.md     # 8-phase plan (150 lines)
+│   ├─ Phase 1: Refactor
+│   ├─ Phase 2: Frontmatter
+│   ├─ Phase 3: Structure
+│   └─ ... (all 8 phases)
+│
+└── TESTING.md            # Test strategy (80 lines)
+    ├─ Test categories
+    ├─ Test cases
+    └─ Integration tests
+
+Total: ~730 lines, but chunked for comprehension
+Largest file: 150 lines (manageable)
+README.md: Entry point, links to details
+```
+
+**Benefits**:
+- Each file fits in <1 screen
+- Can edit one concern without touching others
+- Reduces corruption risk (smaller, focused edits)
+- AI agents can load just what they need
+- Easier to review and maintain
+- Better separation of concerns
+
+## Future Tooling
+
+### Detection: `lean-spec check --complexity`
+
+```bash
+$ lean-spec check --complexity
+
+Complexity Analysis:
+  ⚠ 3 specs may be too complex:
+  
+    018-spec-validation (591 lines, 43 sections)
+      → High complexity
+      → Suggest: Split into sub-specs
+      → Files: VALIDATION-RULES.md, CLI-DESIGN.md, IMPLEMENTATION.md, TESTING.md
+  
+    045-unified-dashboard (1,166 lines, 58 sections)
+      → Very high complexity
+      → Suggest: Consider if this should be multiple specs
+      → Or split into: DESIGN.md, VELOCITY.md, DASHBOARD.md
+  
+    043-official-launch (408 lines, 3 phases)
+      → Moderate complexity
+      → Consider: Use PHASES.md for multi-phase breakdown
+
+Recommendations:
+  - Review specs over 400 lines
+  - Use sub-spec files (spec 012) to split concerns
+  - See: lean-spec view 012 for guidance
+```
+
+### Guided Splitting (v0.3.0+)
+
+```bash
+# Analyze spec complexity
+lean-spec check --complexity
+
+# Guided splitting
+lean-spec split 018 --interactive
+  → Analyzes structure
+  → Suggests split strategy
+  → Creates sub-spec files
+  → Moves content appropriately
+
+# View sub-specs
+lean-spec view 018            # Shows README.md
+lean-spec view 018 --all      # Lists all sub-specs
+lean-spec view 018/DESIGN     # Views specific sub-spec
+
+# Open in editor
+lean-spec open 018            # Opens README.md
+lean-spec open 018 --files    # Opens all sub-specs
+```
+
+## Warning Signs
+
+Your spec might be too complex if:
+- ⚠️ It takes >10 minutes to read through
+- ⚠️ You can't summarize it in 2 paragraphs
+- ⚠️ Recent edits caused corruption
+- ⚠️ You're scrolling endlessly to find information
+- ⚠️ Implementation plan has >8 phases
+
+**Action**: Split using sub-specs, don't just keep growing the file.
+
+## Documentation Updates
+
+### AGENTS.md Template
+
+```markdown
+## Spec Complexity Guidelines
+
+### Single File vs Sub-Specs
+
+**Keep as single file when**:
+- Under 300 lines
+- Can be read/understood in 5-10 minutes
+- Single, focused concern
+- Implementation plan <6 phases
+
+**Consider splitting when**:
+- Over 400 lines
+- Multiple distinct concerns (design + config + testing + examples)
+- AI tools corrupt the spec during edits
+- Updates frequently cause inconsistencies
+- Implementation has >6 phases
+
+**How to split** (see spec 012):
+- README.md: Overview, decision, high-level design
+- DESIGN.md: Detailed design and architecture
+- IMPLEMENTATION.md: Implementation plan with phases
+- TESTING.md: Test strategy and cases
+- CONFIGURATION.md: Config examples and schemas
+- {CONCERN}.md: Other specific concerns (API, MIGRATION, etc.)
+```
+
+### Template Hints
+
+```markdown
+## Plan
+
+<!-- Break down implementation into steps -->
+
+<!-- 💡 TIP: If your plan has >6 phases or this spec approaches 
+     400 lines, consider using sub-spec files:
+     - IMPLEMENTATION.md for detailed implementation
+     - See spec 012 for guidance on splitting -->
+```

package/.next/standalone/packages/ui/dist/standalone/specs/048-spec-complexity-analysis/README.md

@@ -0,0 +1,149 @@
+---
+status: complete
+created: '2025-11-04'
+tags:
+  - philosophy
+  - quality
+  - lean-principle
+  - meta
+priority: critical
+related:
+  - 018-spec-validation
+  - 012-sub-spec-files
+  - 043-official-launch-02
+created_at: '2025-11-04T00:00:00Z'
+updated_at: '2025-11-06T21:15:00Z'
+completed_at: '2025-11-05T05:03:54.952Z'
+completed: '2025-11-05'
+transitions:
+  - status: complete
+    at: '2025-11-05T05:03:54.952Z'
+---
+
+# When Specs Become Too Complex
+
+> **Status**: ✅ Complete · **Priority**: Critical · **Created**: 2025-11-04 · **Tags**: philosophy, quality, lean-principle, meta
+
+**Split into sub-specs for Context Economy** - See detailed sections below
+
+## Overview
+
+**The Irony**: We're building LeanSpec to solve "specs that are too complex for AI," yet our own specs were becoming exactly what we're trying to prevent.
+
+### The Evidence
+
+- Spec 018 (spec-validation): **591 lines**, 43 sections, 13 code blocks
+- Spec 045 (unified-dashboard): **1,166 lines** (largest spec in project)
+- Spec 043 (official-launch): **408 lines** with 3 distinct phases
+- Multiple instances of spec corruption from complex editing
+
+### Core Philosophy Conflict
+
+```markdown
+# From our README:
+"Context overload - 30-page documents blow up the AI's context window"
+"Write only what matters - Clear intent AI can act on, not 50 pages of noise"
+"Keep it minimal - If it doesn't add clarity, cut it"
+
+# Reality (before this spec):
+- 591-line spec with 8 implementation phases
+- Specs getting corrupted from multi-replace operations
+- AI agents struggling to maintain consistency
+```
+
+**The Question**: Are we practicing what we preach?
+
+**The Answer**: Not yet - but we're fixing it through dogfooding.
+
+## Key Findings
+
+### Quantitative Thresholds
+
+- **<300 lines**: ✅ Ideal, keep as single file
+- **300-400 lines**: ⚠️ Warning zone, consider simplifying or splitting
+- **>400 lines**: 🔴 Strong candidate for splitting
+- **>600 lines**: 🔴 Almost certainly should be split
+
+### The Paradox
+
+We built sub-spec files (spec 012) to solve this exact problem, but never used them ourselves! We were experiencing the problem we set out to solve.
+
+### The Solution
+
+Apply our own principles:
+1. Establish clear complexity thresholds (Context Economy)
+2. Use sub-spec files when specs exceed 400 lines
+3. Add validation to catch violations automatically
+4. Dogfood our own guidelines
+
+## Quick Reference
+
+### Warning Signs Your Spec is Too Complex
+
+- Takes >10 minutes to read
+- Can't summarize in 2 paragraphs
+- Recent edits caused corruption
+- Scrolling endlessly to find information
+- Implementation plan has >8 phases
+
+**Action**: Split using sub-specs (see spec 012).
+
+### When to Split
+
+Single file OK: <300 lines, single concern, <6 phases
+
+Consider splitting: >400 lines, multiple concerns, >6 phases
+
+Use sub-specs:
+- README.md: Overview + decision
+- DESIGN.md: Detailed design
+- IMPLEMENTATION.md: Implementation plan
+- TESTING.md: Test strategy
+- {CONCERN}.md: Specific concerns
+
+## Sub-Specs
+
+Detailed information split for Context Economy (<400 lines per file):
+
+- **[FINDINGS.md](./FINDINGS.md)** - Problem analysis, symptoms, root causes, the paradox
+- **[GUIDELINES.md](./GUIDELINES.md)** - When to split, decision tree, thresholds, case studies
+
+## Status
+
+✅ **COMPLETE** - Guidelines established, validation added, specs 018 and 045 successfully split.
+
+### Implementation Summary
+
+**Phase 1: Establish Guidelines** ✅
+- Defined complexity thresholds (300/400/600 lines)
+- Created decision tree for when to split
+- Documented in AGENTS.md
+
+**Phase 2: Add Detection** ✅  
+- Line count detection in `lean-spec validate`
+- Warnings for specs >400 lines
+- Sub-spec validation
+
+**Phase 3: Dogfood** ✅
+- Spec 018 split into 6 focused sub-specs
+- Spec 045 split into 5 focused sub-specs
+- Spec 048 (this spec) split into sub-specs
+
+**Phase 4: Future Enhancements** (v0.3.0+)
+- `lean-spec split` command for guided splitting
+- `lean-spec check --complexity` for detailed analysis
+- Advanced sub-spec navigation
+
+## Impact
+
+### Before Dogfooding
+- 3 specs >600 lines (Context Economy violations)
+- No enforcement mechanism
+- AI corruption incidents
+
+### After Dogfooding
+- All specs <400 lines (or split into sub-specs)
+- Automatic validation catches violations
+- Practicing what we preach ✅
+
+This spec established the principle that drove our dogfooding effort in v0.2.0.

package/.next/standalone/packages/ui/dist/standalone/specs/049-leanspec-first-principles/ANALYSIS-COMPARISONS.md

@@ -0,0 +1,175 @@
+- Heavy review processes
+- Separation: Design doc → Implementation → Maintenance doc
+
+**Typical Scale:**
+- Google Design Docs: 20-50 pages typical
+- AWS RFCs: Can be 100+ pages
+- Enterprise PRDs: Often 30-50 pages
+
+**Root Difference:**
+- Traditional: "Document everything before building"
+- LeanSpec: "Document just enough to start, evolve as you learn"
+
+**Why Different:**
+- Traditional assumes: Complete understanding upfront possible
+- LeanSpec assumes: Understanding emerges through building
+- Traditional: Human-only communication
+- LeanSpec: Human + AI communication
+
+### Agile/Lean Methodologies
+
+**Shared Principles:**
+- Minimal viable documentation
+- Iterative development
+- Respond to change over following plan
+
+**LeanSpec Addition:**
+- Structured documentation for AI agents
+- Clear metadata for tooling
+- Visual management (boards, timelines)
+- Spec-driven (not just story-driven)
+
+**LeanSpec = Agile Principles + Structure for AI + Developer Experience**
+
+## Part 4: Thought Experiments
+
+### Experiment 1: "Infinite Context Windows"
+
+**Question:** If context windows were infinite, what would change?
+
+**Analysis:**
+- Would we write longer specs? Probably yes.
+- Would that be better? NO.
+- Why not? Human cognitive limits still apply.
+- Reading time still costs money.
+- Maintenance burden still increases with length.
+- Signal-to-noise ratio still matters.
+
+**Revelation:** Context window limits are a SYMPTOM, not the root cause.
+
+**Root Cause:** The real constraint is attention—both human and AI. Even with infinite storage, focused attention is finite.
+
+**First Principle This Reveals:** 
+**"Optimize for attention, not storage."**
+
+### Experiment 2: "Only 3 Rules"
+
+**Question:** If we could only keep 3 rules, which ones?
+
+**My picks:**
+1. **Context Economy** - Fit in working memory
+2. **Signal-to-Noise** - Say what matters, nothing more
+3. **Intent Over Implementation** - Capture "why," let "how" emerge
+
+**Why these 3?**
+- They're constraints, not preferences
+- Everything else can derive from them
+- They apply to all contexts (solo → enterprise)
+
+**Revelation:** These aren't rules we chose—they're constraints we must work within.
+
+### Experiment 3: "Violate X, Keep Y"
+
+**Question:** If a user violates rule X but follows Y, is it still LeanSpec?
+
+**Test Cases:**
+
+1. **1000-line spec but it's all signal (no noise)**
+   - Violates: Context economy
+   - Keeps: Signal-to-noise
+   - Verdict: NOT LeanSpec (context limits are physics)
+
+2. **5-line spec that's vague and ambiguous**
+   - Violates: Clarity
+   - Keeps: Context economy
+   - Verdict: NOT LeanSpec (clarity is the point)
+
+3. **Perfect spec but never updated after code changes**
+   - Violates: Living documentation
+   - Keeps: Clarity + context economy
+   - Verdict: NOT LeanSpec (stale specs are harmful)
+
+4. **Uses different template every time**
+   - Violates: Structural consistency
+   - Keeps: Everything else
+   - Verdict: Still LeanSpec (templates are helpful but not essential)
+
+**Revelation:** Some principles are MUST-HAVE (clarity, context economy, living), others are SHOULD-HAVE (consistency).
+
+### Experiment 4: "What Makes LeanSpec Obsolete?"
+
+**Question:** If X happened, LeanSpec wouldn't be needed. What is X?
+
+**Candidate 1:** AI gets good enough it doesn't need specs
+- But: Humans still need specs
+- And: Human-AI communication still needs shared context
+- Verdict: Won't make LeanSpec obsolete
+
+**Candidate 2:** AI can perfectly read entire codebases
+- But: Codebases don't contain "why" decisions were made
+- And: Intent isn't in the code
+- Verdict: Won't make LeanSpec obsolete
+
+**Candidate 3:** Perfect automated spec generation from code
+- But: Code shows "what," not "why"
+- And: Future intent isn't in current code
+- Verdict: Won't make LeanSpec obsolete
+
+**Candidate 4:** Telepathic human-AI interface (sci-fi)
+- No need for written communication
+- Verdict: This would make LeanSpec obsolete!
+
+**Revelation:** LeanSpec exists because of the gap between human intent and machine understanding. As long as that gap exists, we need a bridge.
+
+**First Principle This Reveals:**
+**"Bridge the intent gap between human and machine."**
+
+## Part 5: Our Own Evolution Analysis
+
+### What Worked Well
+
+1. **Templates system** - Convention reduces decision fatigue
+2. **Frontmatter** - Structured metadata enables tooling
+3. **CLI tools** - Commands make specs actionable
+4. **Flat folder structure** - Simple navigation, easy references
+5. **Status tracking** - Clear project visibility
+
+**Pattern:** Structure that enables without constraining.
+
+### What Caused Problems
+
+1. **Specs growing to 600-1,166 lines** - Violated context economy
+2. **Built sub-spec feature but didn't use it** - Dogfooding failure
+3. **Spec corruption** - Tool struggling with its own output
+4. **Multiple similar sections** - Unclear purpose/hierarchy
+
+**Pattern:** Principles without enforcement mechanisms.
+
+### Root Cause Analysis
+
+**Problem:** We built sub-specs (spec 012) but never used them.
+
+**Why?** 
+- No pain threshold defined
+- No tooling to detect problem
+- No culture of "split early"
+- Completeness bias (want everything in one place)
+
+**Lesson:** Good principles need operationalization (tooling + culture + metrics).
+
+### What Would Have Prevented the 600-Line Spec Problem?
+
+**If we had:**
+1. **Clear threshold**: "300 lines = warning, 400 lines = split"
+2. **Automated detection**: `lean-spec validate --max-lines 400`
+3. **Cultural norm**: "Split specs proactively, not reactively"
+4. **Tooling support**: `lean-spec split <spec>` command
+
+**First Principle This Reveals:**
+**"Principles need operationalization to be followed."**
+
+## Related Documents
+
+- [Main Spec](README.md) - Overview and findings summary
+- [First Principles](FIRST-PRINCIPLES.md) - The 5 crystal stone rules
+- [Operationalization](OPERATIONALIZATION.md) - How to enforce principles