@leanspec/ui 0.2.7-dev.20251126100750 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/054-validate-output-lint-style/OUTPUT-FORMAT-SPEC.md

@@ -0,0 +1,146 @@
+# Output Format Specification
+
+## Output Structure
+
+**Principle: File-Centric, Severity-First**
+
+Show each spec once with all its issues grouped together:
+
+```bash
+$ lean-spec validate
+
+Validating 25 specs...
+
+045-unified-dashboard/README.md
+  error    Spec exceeds 400 lines (1169 lines)                   max-lines
+  warning  Orphaned sub-spec: IMPLEMENTATION.md                  sub-specs
+           → Add a link to IMPLEMENTATION.md in README.md
+
+045-unified-dashboard/IMPLEMENTATION.md
+  error    Sub-spec exceeds 400 lines (685 lines)                max-lines
+           → Consider splitting or simplifying
+
+046-stats-dashboard-refactor/README.md
+  error    Spec exceeds 400 lines (685 lines)                    max-lines
+           → Consider splitting into sub-specs (see spec 012)
+
+048-spec-complexity-analysis/README.md
+  error    Spec exceeds 400 lines (601 lines)                    max-lines
+           → Consider splitting into sub-specs (see spec 012)
+
+049-leanspec-first-principles/README.md
+  warning  Spec approaching limit (373/400 lines)                max-lines
+           → Consider simplification or splitting
+
+049-leanspec-first-principles/ANALYSIS.md
+  error    Sub-spec exceeds 400 lines (428 lines)                max-lines
+           → Consider further splitting
+
+✖ 5 errors, 13 warnings (25 specs checked, 19 clean)
+
+Run with --verbose to see passing specs.
+```
+
+## Format Specification
+
+**Structure:**
+
+```
+<spec-path>/<file>
+  <severity>  <message>  <rule>
+             <suggestion>
+  <severity>  <message>  <rule>
+
+<spec-path>/<file>
+  ...
+
+<summary>
+```
+
+**Alignment:**
+
+```
+<severity>: 7 chars left-aligned  ("error  " or "warning")
+<message>:  50 chars left-aligned (truncate if needed)
+<rule>:     right-aligned after message
+```
+
+**Colors:**
+
+- `error` - Red text
+- `warning` - Yellow text
+- `suggestion` (→ line) - Gray text
+- `summary` - Bold white (errors) or bold yellow (warnings only)
+- File paths - Cyan underlined (like ESLint)
+
+**Summary Format:**
+
+```
+✖ <N> errors, <M> warnings (<total> specs checked, <clean> clean)
+```
+
+If only warnings:
+```
+⚠ <M> warnings (<total> specs checked, <clean> clean)
+```
+
+If all pass:
+```
+✓ All <total> specs passed
+```
+
+## CLI Flags
+
+**New Flags:**
+
+```bash
+--verbose     # Show passing specs (default: false)
+--quiet       # Suppress all output except errors (no warnings, no summary)
+--format      # Output format: 'default' | 'json' | 'compact'
+--rule        # Filter by rule name (e.g., --rule=max-lines)
+```
+
+**Examples:**
+
+```bash
+# Default: Show only issues, quiet success
+lean-spec validate
+
+# Show everything including passing specs
+lean-spec validate --verbose
+
+# Only errors, no warnings
+lean-spec validate --quiet
+
+# JSON for CI integration
+lean-spec validate --format=json
+
+# Check only line count issues
+lean-spec validate --rule=max-lines
+```
+
+## Severity Hierarchy
+
+Always show errors before warnings within a file:
+
+```bash
+045-unified-dashboard/README.md
+  error    Spec exceeds 400 lines (1169 lines)      # Error first
+  warning  Orphaned sub-spec: IMPLEMENTATION.md      # Warning second
+```
+
+## Verbose Mode
+
+Show passing specs only when requested:
+
+```bash
+$ lean-spec validate --verbose
+
+# ... issues shown first ...
+
+✓ 19 specs passed:
+  014-complete-custom-frontmatter
+  017-vscode-extension
+  024-pattern-aware-list-grouping
+  ...
+```

package/.next/standalone/packages/ui/dist/standalone/specs/054-validate-output-lint-style/README.md

@@ -0,0 +1,175 @@
+---
+status: complete
+created: '2025-11-06'
+tags:
+  - validation
+  - cli
+  - ux
+  - v0.2.0
+priority: high
+related:
+  - '043'
+created_at: '2025-11-07T03:20:34.342Z'
+updated_at: '2025-11-07T03:20:34.342Z'
+completed_at: '2025-11-07T03:20:34.342Z'
+completed: '2025-11-07'
+transitions:
+  - status: complete
+    at: '2025-11-07T03:20:34.342Z'
+---
+
+# Lint-Style Validate Output
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-06 · **Tags**: validation, cli, ux, v0.2.0
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Redesign `lean-spec validate` output to follow mainstream lint tool conventions (ESLint, TypeScript, Prettier, etc.) for better consistency, clarity, and developer familiarity.
+
+**Current Problems:**
+
+1. **Inconsistent grouping logic** - Mixes validator-based and spec-based grouping
+2. **Verbose for clean files** - Shows every passing spec (noisy when 20+ specs pass)
+3. **Poor severity hierarchy** - Errors and warnings mixed in output flow
+4. **Unfamiliar format** - Doesn't match tools developers use daily
+5. **Redundant information** - Line count shown 3 times for same spec
+
+**Inspiration from Mainstream Tools:**
+
+```bash
+# ESLint - File-centric, severity-grouped, clean summary
+/src/utils.ts
+  12:5   error    'foo' is not defined         no-undef
+  15:10  warning  Unexpected console statement no-console
+
+/src/index.ts
+  8:3   error    Missing semicolon            semi
+
+✖ 2 errors, 1 warning (2 files, 5 files clean)
+
+# TypeScript - Location-first, concise messages
+src/utils.ts(12,5): error TS2304: Cannot find name 'foo'.
+src/index.ts(8,3): error TS1005: ';' expected.
+
+Found 2 errors in 2 files.
+
+# Prettier - Clear pass/fail, actionable suggestions
+Checking formatting...
+[warn] src/utils.ts
+[warn] src/index.ts
+Code style issues found. Run `prettier --write` to fix.
+```
+
+**Key Learnings:**
+
+1. **File-centric grouping** - Group by file, not by rule type
+2. **Severity-first** - Show errors before warnings
+3. **Quiet success** - Only summarize passing files
+4. **Actionable suggestions** - Clear fix recommendations
+5. **Consistent formatting** - Predictable structure across runs
+
+## Design
+
+### Summary
+
+The new validation output follows mainstream lint tool conventions (ESLint, TypeScript, Prettier) with these key improvements:
+
+1. **File-centric grouping** - All issues for a spec shown together (not by validator type)
+2. **Quiet success by default** - Only show specs with issues, summarize passing specs
+3. **Severity-first hierarchy** - Errors shown before warnings within each file
+4. **Aligned column format** - Consistent spacing like ESLint: `<severity> <message> <rule>`
+5. **CLI flags** - `--verbose`, `--quiet`, `--format`, `--rule` for different use cases
+
+**Example output:**
+
+```bash
+$ lean-spec validate
+
+Validating 25 specs...
+
+045-unified-dashboard/README.md
+  error    Spec exceeds 400 lines (1169 lines)                   max-lines
+  warning  Orphaned sub-spec: IMPLEMENTATION.md                  sub-specs
+
+✖ 5 errors, 13 warnings (25 specs checked, 19 clean)
+```
+
+### Detailed Specifications
+
+Complete design details are documented in sub-specs:
+
+- **[OUTPUT-FORMAT-SPEC.md](./OUTPUT-FORMAT-SPEC.md)** - Format structure, alignment rules, CLI flags, examples
+- **[DESIGN-DECISIONS.md](./DESIGN-DECISIONS.md)** - Design rationale, trade-offs, backward compatibility
+
+### Implementation Strategy
+
+**Phase 1:** Refactor output logic (2-3 hours)  
+**Phase 2:** Implement new format (2-3 hours)  
+**Phase 3:** Add CLI flags (1-2 hours)  
+**Phase 4:** Testing (2 hours)  
+
+**Total Effort:** 1-2 days
+
+## Plan
+
+**Status:** 📅 Planned for v0.2.0 (Pre-launch polish)
+
+- [ ] Phase 1: Refactor output logic (extract formatter module)
+- [ ] Phase 2: Implement new file-centric format
+- [ ] Phase 3: Add CLI flags (--verbose, --quiet, --format)
+- [ ] Phase 4: Update tests and documentation
+- [ ] Dogfood: Run on lean-spec repo and verify clarity
+- [ ] Update CHANGELOG and migration guide
+
+**Estimated Effort:** 1-2 days
+
+**Priority:** High - Critical for v0.2.0 UX polish
+
+## Test
+
+**Verification Strategy:**
+
+- [ ] Output matches ESLint-style format (file-centric, aligned columns)
+- [ ] Default mode hides passing specs (quiet success)
+- [ ] `--verbose` shows all specs including passing ones
+- [ ] `--quiet` suppresses warnings and summary
+- [ ] `--format=json` produces valid JSON output
+- [ ] Exit code 0 for warnings-only, 1 for errors (unchanged)
+- [ ] Snapshot tests for output format stability
+- [ ] Real repository test: `lean-spec validate` on lean-spec itself
+
+**Success Criteria:**
+
+- 60% reduction in output size for clean runs
+- Issues are immediately visible (no scrolling)
+- Beta tester feedback: "Looks like ESLint"
+
+## Notes
+
+### Why This Matters
+
+**Developer Familiarity:** Matches ESLint/TypeScript/Prettier conventions = lower cognitive load
+
+**Signal-to-Noise:** 60% reduction in output (15-20 lines vs 50+ lines for 25 specs)
+
+**Actionability:** Clear severity hierarchy, file-centric grouping, visible suggestions
+
+### Success Metrics
+
+**Quantitative:**
+- Output size: 60% reduction for clean runs
+- Time to find issue: <5 seconds (vs 10-15s currently)
+
+**Qualitative:**
+- Output "feels like" ESLint/TypeScript
+- Beta tester feedback: "Looks like ESLint" positive sentiment
+
+### Future Enhancements (Post v0.2.0)
+
+- **Auto-fix:** `lean-spec validate --fix`
+- **Watch mode:** `lean-spec validate --watch`
+- **Custom formatters:** Plugin system for CI-specific formats
+- **Rule configuration:** `.lean-spec/rules.json` to disable/configure rules

package/.next/standalone/packages/ui/dist/standalone/specs/055-readme-redesign-ai-first/ANALYSIS-PART1.md

@@ -0,0 +1,397 @@
+# README Analysis: Critical Assessment & Strategy
+
+**Date**: 2025-11-06  
+**Scope**: Parts 1-6 - Analysis of current README and strategic foundation  
+**See also**: [ANALYSIS-PART2.md](ANALYSIS-PART2.md) for implementation recommendations
+
+---
+
+## Part 1: Critical Analysis of Current README
+
+### What Works Well ✅
+
+1. **Visual Identity**
+   - Logo + badges create professional first impression
+   - Diff block makes problem/solution instantly graspable
+   - Table layout for features is scannable
+
+2. **Clear Problem Statement**
+   - "30-page specs that AI can't fit in context" → relatable pain
+   - "Rigid templates that don't match your workflow" → common frustration
+   - Contrasts traditional SDD problems with LeanSpec solutions
+
+3. **Progressive Disclosure Structure**
+   - Why → Features → Principles → Quick Start → Learn More
+   - Logical flow from motivation to action
+
+4. **First Principles Section**
+   - New addition grounds everything in fundamentals
+   - Links to deep dive (good for curious readers)
+
+### Critical Weaknesses ❌
+
+1. **Buried Lede Problem**
+   - Most compelling value prop ("specs clear enough for AI to implement") is in paragraph 3
+   - Should be in the hero section, not buried
+   
+2. **Generic Positioning**
+   - "Spec-Driven Development for the AI era" → vague
+   - Could describe many tools
+   - Doesn't differentiate from ADRs, RFCs, Linear, etc.
+
+3. **Weak Emotional Hook**
+   - Current hook: "Traditional SDD is too heavy or too light"
+   - Missing: The pain of maintaining specs, AI context overflow, specs getting stale
+   - Doesn't make reader feel "YES, this is MY problem!"
+
+4. **Feature Presentation Lacks Punch**
+   - "Context Economy" → jargon-y, requires explanation
+   - "Progressive Growth" → could mean anything
+   - Features don't connect to real user pain points
+
+5. **Unclear Target Audience**
+   - Is it for teams using Cursor/Copilot?
+   - Solo developers tired of heavy processes?
+   - Engineering leaders wanting SDD without overhead?
+   - Tries to appeal to everyone, compelling to no one
+
+6. **Missing Social Proof**
+   - No testimonials, usage stats, or "used by"
+   - No concrete before/after examples
+   - Hard to trust it works without evidence
+
+7. **Call-to-Action Diffusion**
+   - Multiple CTAs (Quick Start, Examples, Docs)
+   - No clear primary action
+   - Paradox of choice → lower conversion
+
+8. **Philosophy Integration Issues**
+   - First Principles section added but not woven throughout
+   - Feels tacked on rather than central
+   - Most readers won't read the deep dive link
+
+---
+
+## Part 2: User Journey & Conversion Funnel Analysis
+
+### The Ideal Journey
+
+```
+AWARENESS → INTEREST → DESIRE → ACTION
+   ↓            ↓          ↓         ↓
+Problem     "This is    "I need    Install
+Resonance   for me"     this!"     & Try
+```
+
+### Current Journey Breakdown
+
+**Stage 1: Awareness (First 3 Seconds)**
+- ✅ Logo creates credibility
+- ❌ Tagline "Spec-Driven Development for the AI era" is too generic
+- ❌ No immediate "aha moment"
+- **Result**: Many bounce without reading further
+
+**Stage 2: Interest (Next 15 Seconds)**
+- ✅ Diff block shows problem/solution
+- ⚠️ Problem statement is abstract ("too heavy or too light")
+- ❌ Missing concrete examples of the pain
+- **Result**: Some interest but not hooked
+
+**Stage 3: Desire (Next 60 Seconds)**
+- ⚠️ Features are listed but not connected to outcomes
+- ❌ No social proof or validation
+- ⚠️ First Principles exist but not integrated
+- **Result**: Intellectually interesting but not emotionally compelling
+
+**Stage 4: Action (Install Decision)**
+- ✅ Quick Start is clear
+- ❌ No clear "quick win" promised
+- ❌ Unclear what happens after install
+- **Result**: High friction to try
+
+### Friction Points
+
+1. **Cognitive Load**: Too much to process
+2. **Unclear Differentiation**: Why not just use ADRs + Linear?
+3. **Trust Gap**: No proof this works
+4. **Effort Uncertainty**: How much work to adopt?
+5. **Value Ambiguity**: What do I get for that effort?
+
+---
+
+## Part 3: Psychology & Persuasion Analysis
+
+### What Makes Developer Tools Go Viral?
+
+**Pattern Analysis from Successful Tools:**
+
+1. **Vite**: "Next Generation Frontend Tooling" + instant server start demo
+   - **Hook**: Speed (instant vs. slow bundlers)
+   - **Proof**: Live demo you can see
+   
+2. **Cursor**: "The AI-first Code Editor"
+   - **Hook**: AI writes code for you
+   - **Proof**: Videos of it working
+   
+3. **Tailwind**: "Utility-first CSS framework"
+   - **Hook**: No more context switching
+   - **Proof**: Before/after code examples
+
+4. **Zod**: "TypeScript-first schema validation"
+   - **Hook**: Type inference magic
+   - **Proof**: Code example shows the magic
+
+**Common Success Patterns:**
+- ✅ Single, clear superpower
+- ✅ Instant "aha moment" 
+- ✅ Concrete before/after example
+- ✅ Visual or executable proof
+- ✅ Clear target audience
+
+### Emotional Drivers for LeanSpec Adoption
+
+**Pain Points to Activate:**
+
+1. **AI Context Overflow** (HIGH PAIN)
+   - "I paste my spec and Cursor says 'context too large'"
+   - "AI hallucinate because my spec is 2000 lines"
+   - Emotional response: Frustration, wasted time
+
+2. **Spec Staleness** (HIGH PAIN)
+   - "Our specs are always outdated"
+   - "Nobody maintains them because it's too painful"
+   - Emotional response: Guilt, resignation
+
+3. **Process Overhead** (MEDIUM PAIN)
+   - "We tried RFC process but it's too heavy"
+   - "We tried just code but AI agents get lost"
+   - Emotional response: Seeking middle ground
+
+4. **Team Alignment** (MEDIUM PAIN)
+   - "Engineers don't know what to build"
+   - "AI agents implement the wrong thing"
+   - Emotional response: Chaos, miscommunication
+
+**Aspirations to Activate:**
+
+1. **AI Superpowers** (HIGH DESIRE)
+   - "AI agents that implement full features"
+   - "Specs that don't need human clarification"
+   - Emotional response: Excitement, possibility
+
+2. **Effortless Documentation** (HIGH DESIRE)
+   - "Docs that stay in sync with code"
+   - "Specs that are actually useful"
+   - Emotional response: Relief, satisfaction
+
+3. **Team Efficiency** (MEDIUM DESIRE)
+   - "Everyone knows what to build"
+   - "New team members onboard fast"
+   - Emotional response: Pride, effectiveness
+
+### Persuasion Principles to Apply
+
+1. **Specificity Beats Abstraction**
+   - ❌ "Context Economy" → ⚠️ Jargon
+   - ✅ "Specs under 300 lines" → Concrete
+   - ✅ "Fits in AI context window" → Tangible benefit
+
+2. **Contrast Creates Clarity**
+   - Show old way vs. new way
+   - 2000-line RFC vs. 250-line LeanSpec
+   - 30-minute spec writing vs. 5-minute
+
+3. **Social Proof Removes Risk**
+   - "Used by X teams"
+   - "Y specs created"
+   - Testimonials from real users
+
+4. **Progressive Commitment**
+   - Small first step (install + create one spec)
+   - Quick win (see it work)
+   - Deeper engagement (adopt for team)
+
+5. **Authority Through Dogfooding**
+   - "Built using LeanSpec itself"
+   - "54+ specs, all under 400 lines"
+   - "We practice what we preach"
+
+---
+
+## Part 4: The "Aha Moment" Problem
+
+### Current README's Aha Moment
+**"Specs clear enough for AI agents to implement. Lean enough for humans to maintain."**
+
+**Analysis:**
+- ✅ Good contrast (AI + human)
+- ⚠️ Requires mental work to imagine
+- ❌ Not visceral or immediate
+- ❌ No proof shown
+
+### Better Aha Moments (Options)
+
+**Option A: The Context Window Hook**
+```
+Your specs are too big for AI to read.
+
+❌ Traditional RFC: 2,847 lines → Context overflow → AI hallucinates
+✅ LeanSpec: 287 lines → Fits perfectly → AI implements correctly
+
+Keep your specs under 300 lines. Give AI the full context.
+```
+
+**Why it works:**
+- Concrete numbers
+- Visual contrast
+- Immediate pain → immediate solution
+- Ties to AI era positioning
+
+**Option B: The Maintenance Hook**
+```
+You know your docs are stale. We all do.
+
+The problem isn't discipline. It's that traditional specs are:
+• Too long to update (30+ pages)
+• Too disconnected from code
+• Too painful to maintain
+
+LeanSpec: Short enough to update. Structured enough to enforce. 
+Lightweight enough to actually maintain.
+```
+
+**Why it works:**
+- Addresses universal pain
+- Empathetic tone
+- Reframes from discipline to system design
+- Promises relief
+
+**Option C: The AI Superpower Hook**
+```
+Give AI the perfect spec. Get the perfect implementation.
+
+When your spec is:
+✅ Under 300 lines (fits in context)
+✅ Intent-focused (not just implementation)
+✅ Structured for machines (frontmatter + markdown)
+
+AI agents can implement entire features with 90% accuracy.
+
+This is SDD for the AI era.
+```
+
+**Why it works:**
+- Leads with aspiration (superpower)
+- Concrete criteria
+- Quantified outcome (90% accuracy)
+- Positions for future
+
+**Recommendation**: Combine A + C
+- Lead with pain (context overflow)
+- Promise superpower (AI implementation)
+- Back with specifics (under 300 lines)
+
+---
+
+## Part 5: Audience Segmentation & Messaging
+
+### Primary Audiences (Ranked by Fit)
+
+**1. AI-First Developers (BEST FIT)**
+- Use Cursor, Copilot, Aider daily
+- Frustrated by AI context limits
+- Want specs that AI can act on
+- Solo or small team (2-5 people)
+
+**Message:**
+> "Stop fighting AI context limits. LeanSpec keeps specs under 300 lines—short enough for AI to read, clear enough for AI to implement."
+
+**2. Engineering Leaders at Scaling Startups (HIGH FIT)**
+- Tried heavyweight SDD (RFCs), too slow
+- Tried no process, chaos at 10+ engineers
+- Need middle ground
+- Want team alignment without bureaucracy
+
+**Message:**
+> "SDD without the overhead. Start minimal (just status + created). Add structure as you scale. Used from solo dev to 50+ person teams."
+
+**3. Teams Struggling with Stale Docs (MEDIUM FIT)**
+- Have specs but nobody maintains them
+- Docs always outdated
+- Tried tools but gave up
+- Need something lightweight
+
+**Message:**
+> "Specs you'll actually maintain. Under 300 lines per spec. 5 minutes to update. Stays in sync with code because it's not painful."
+
+**4. AI Agent Developers (EMERGING FIT)**
+- Building autonomous coding agents
+- Need structured input format
+- Want machine-readable specs
+- MCP integration is key
+
+**Message:**
+> "MCP-native specs for AI agents. Structured frontmatter. Clear intent. Perfect for autonomous coding workflows."
+
+### Anti-Audiences (Who This ISN'T For)
+
+1. **Enterprise with Complex Compliance** → Need heavyweight docs
+2. **API-Only Projects** → Use OpenAPI/code comments
+3. **Documentation Maximalists** → Want comprehensive docs
+4. **Teams Happy with Current Process** → No pain = no need
+
+**Key Decision**: Focus messaging on Audience #1 (AI-First Developers) with secondary appeal to #2 (Engineering Leaders). This is 80% of potential users.
+
+---
+
+## Part 6: Structural Recommendations
+
+### Proposed New Structure
+
+```
+1. HERO
+   - Hook (pain + promise)
+   - Visual proof (before/after)
+   - Primary CTA
+
+2. THE PROBLEM (Why This Exists)
+   - 3 concrete pain points
+   - Each with example
+   
+3. THE SOLUTION (How It Works)
+   - Show, don't tell
+   - Actual spec example
+   - Highlight key principles
+   
+4. CORE PRINCIPLES (Philosophy)
+   - 5 first principles
+   - Each with 1-line explanation
+   - Visual/icon for each
+   
+5. HOW IT WORKS (Mechanics)
+   - Quick Start (install → create → view)
+   - 30-second demo
+   
+6. WHO'S USING IT (Social Proof)
+   - Usage stats
+   - Testimonials (if available)
+   - Dogfooding callout
+   
+7. QUICK WINS (Get Started)
+   - Single, clear CTA
+   - Promise quick result
+   
+8. LEARN MORE (For Deep Divers)
+   - Links to docs
+   - Links to examples
+   - Community
+```
+
+### Length Target
+- Current: ~220 lines
+- Target: ~180-200 lines (apply our own Signal-to-Noise principle!)
+- Cut: Redundancy, weak examples, generic statements
+
+---
+
+**Continue to**: [ANALYSIS-PART2.md](ANALYSIS-PART2.md) for specific implementation recommendations, content rewrites, and success metrics.