@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

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

@@ -1,146 +0,0 @@
-# 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

@@ -1,175 +0,0 @@
----
-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

@@ -1,397 +0,0 @@
-# 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.