npm - @leanspec/ui - Versions diffs - 0.2.5 → 0.2.6-dev.20251125010539 - Mend

@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (695) hide show

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

@@ -1,254 +0,0 @@
-# LeanSpec First Principles - Deep Analysis
-> Part of spec: [049-leanspec-first-principles](README.md)
-This document contains the comprehensive analysis that led to the identification of LeanSpec's five first principles.
-## Part 1: Hard Constraints Analysis
-### 1. Physics of AI-Powered Development
-**Unchangeable Technical Constraints:**
-#### Context Window Limits (Hard Technical Constraint)
-- Claude Sonnet: 200K tokens total, ~20-30K effective working memory
-- GPT-4: 128K tokens total, ~8-16K effective working memory
-- Context degradation: Quality degrades significantly beyond 50K tokens
-- Multi-file projects: Context must be shared (specs + code + conversation)
-- 600-line spec ≈ 15-20K tokens = entire working memory for ONE spec
-**Implication:** Specs MUST be bounded in size. This is physics, not preference.
-#### Token Economics (Economic Constraint)
-- Cost per token: $0.003-0.015 per 1K tokens (varies by model)
-- Large specs = repeated token costs on every interaction
-- 1000-line spec read 10 times = 250K-500K tokens = $0.75-$7.50
-**Implication:** Brevity has real economic value.
-#### AI Reasoning Quality Degradation
-- Lost in the middle: AI performs worse with information in middle of long contexts
-- Recency bias: Recent context weighted more heavily than earlier context
-- Attention diffusion: More context = less attention per item
-**Implication:** Focused, structured content > exhaustive documentation.
-#### Need for Unambiguous Instructions
-- AI requires clear, specific guidance
-- Vague principles → inconsistent implementation
-- Ambiguity → hallucination or incorrect assumptions
-**Implication:** Clarity is not optional—it's a functional requirement.
-#### Async Nature of Human-AI Collaboration
-- No real-time clarification loop
-- Must anticipate questions in the spec
-- Context must persist across sessions
-**Implication:** Specs must be self-contained and anticipatory.
-### 2. Human Cognitive Limits
-**Unchangeable Human Constraints:**
-#### Working Memory: 7±2 Items
-- Can hold ~7 concepts simultaneously
-- Beyond that, cognitive overload
-- Deep nesting reduces effective capacity
-**Implication:** Specs should have ≤7 major sections.
-#### Reading Speed and Comprehension
-- Average: 200-300 words/minute (English)
-- Technical docs: 100-150 words/minute (slower)
-- 600 lines ≈ 3000 words ≈ 20-30 minutes reading time
-- Comprehension drops after 10 minutes without breaks
-**Implication:** If spec takes >10 minutes to read, it's too long.
-#### Fatigue from Context Switching
-- Each switch has cognitive cost (~23 minutes to regain focus)
-- Multiple files = multiple switches
-- BUT: Well-organized splits reduce fatigue (progressive disclosure)
-**Implication:** Organization matters more than file count.
-#### Need for Progressive Disclosure
-- Humans learn top-down (overview → details)
-- Can't process all details upfront
-- Need "executive summary" → "details on demand"
-**Implication:** Specs should start broad, link to depth.
-#### Pattern Recognition vs Detailed Analysis
-- Humans excel at patterns, struggle with details
-- Good structure creates recognizable patterns
-- Consistency reduces cognitive load
-**Implication:** Templates and conventions have cognitive value.
-### 3. Evolution and Emergence Patterns
-**How Software Projects Naturally Evolve:**
-#### Complexity Increases Over Time (Entropy Law)
-- Every project trends toward complexity
-- Features accumulate, interactions multiply
-- "Simple" designs become complex through accretion
-**Implication:** Must actively resist complexity creep.
-#### Documentation Decay (Second System Effect)
-- Docs fall out of sync with code
-- Updates to code >> updates to docs
-- Longer docs = faster decay rate
-**Implication:** Minimal docs are more maintainable.
-#### Conway's Law (Organizational Constraint)
-- System structure mirrors communication structure
-- Team size affects optimal spec organization
-- Solo dev ≠ 5-person team ≠ 50-person team
-**Implication:** Structure must scale with team.
-#### Emergence of New Requirements
-- Unknown unknowns emerge during implementation
-- Initial specs are always incomplete
-- Over-specification wastes effort on wrong details
-**Implication:** Specs should be living documents, not blueprints.
-#### Network Effects of Dependencies
-- Changes cascade through dependencies
-- Coupling increases maintenance burden
-- Tight coupling = brittle system
-**Implication:** Loose coupling in specs → easier evolution.
-### 4. Economic Constraints
-**Business Realities:**
-#### Time is Money
-- Developer time is expensive ($50-200/hour)
-- Spec-writing time has opportunity cost
-- Reading time multiplied by team size
-**Implication:** Every word must justify its cost.
-#### Maintenance is More Expensive than Creation
-- Maintenance = 60-80% of software lifecycle cost
-- Complex specs = higher maintenance burden
-- Outdated specs are worse than no specs
-**Implication:** Optimize for maintainability, not initial completeness.
-#### Coordination Costs Scale Quadratically
-- N people = N(N-1)/2 communication paths
-- Larger specs = more coordination needed
-- More coordination = slower development
-**Implication:** Smaller, focused specs reduce coordination overhead.
-## Part 2: What MUST Be True Given These Constraints?
-Given the above constraints, what principles are **forced** to be true?
-### Forced Principle 1: Context Economy
-**Specs must fit in working memory—both human and AI.**
-- Can't violate context window limits (physics)
-- Can't exceed human working memory (biology)
-- Can't afford repeated large context loads (economics)
-**Quantified:**
-- Target: <300 lines (fits in one screen, <10 min read, <10K tokens)
-- Warning: 300-400 lines (borderline)
-- Problem: >400 lines (requires splitting)
-- Crisis: >600 lines (definitely split)
-### Forced Principle 2: Signal-to-Noise Maximization
-**Every word must carry weight; noise is expensive.**
-- Token costs penalize verbosity
-- Cognitive load penalizes noise
-- Maintenance cost penalizes outdated content
-**Quantified:**
-- Every sentence should answer: "What decision does this inform?"
-- Remove anything that doesn't change behavior
-- If AI/human can infer it, don't state it
-### Forced Principle 3: Progressive Complexity
-**Start minimal, add structure only when pain is felt.**
-- Early over-specification wastes effort (emergence)
-- Premature abstraction causes rigidity
-- Team needs evolve over time (Conway's Law)
-**Quantified:**
-- Solo dev: Just intent + plan
-- Small team: Add status, tags, priority
-- Scaling team: Add custom fields as needed
-- Never require upfront what might be needed later
-### Forced Principle 4: Living Documentation
-**Specs evolve with understanding; they're not upfront contracts.**
-- Requirements emerge during implementation
-- Over-specification on unknowns is waste
-- Sync between spec and reality is critical
-**Quantified:**
-- Update spec when understanding changes
-- Incomplete spec > outdated spec
-- Ship code and spec together
-### Forced Principle 5: Intent Over Implementation
-**Clear intent > exhaustive details.**
-- AI needs "why" to make good decisions
-- Humans need "what" to understand goals
-- Details can be discovered/inferred/added later
-**Quantified:**
-- Must have: Problem, solution intent, success criteria
-- Nice to have: Implementation details, examples, edge cases
-- Don't include: Obvious things, inferable things, "maybe" futures
-### Forced Principle 6: Structural Consistency
-**Predictable patterns reduce cognitive load.**
-- Pattern recognition is cheap for humans
-- Consistent structure helps AI navigate
-- Convention reduces decision fatigue
-**Quantified:**
-- Use templates for common patterns
-- Standard naming (TESTING.md, API.md)
-- Consistent frontmatter structure
-### Forced Principle 7: Bridge the Gap
-**Specs exist to align human intent with machine execution.**
-- Humans think in goals and intent
-- Machines execute in steps and logic
-- Gap must be bridged explicitly
-- Both audiences (human + AI) must understand
-**Quantified:**
-- Clear problem statement (human context)
-- Unambiguous requirements (machine clarity)
-- Examples bridge abstract to concrete
-- Test criteria define success objectively
-## Part 3: Comparison to Alternatives
-### Traditional SDD (RFCs, ADRs, PRDs)
-**Traditional Approach:**
-- Comprehensive upfront documentation
-- Fixed formats (RFC template, ADR template)
-- Heavy review processes

package/.next/standalone/packages/ui/dist/standalone/specs/049-leanspec-first-principles/FIRST-PRINCIPLES.md DELETED Viewed

@@ -1,376 +0,0 @@
-# The Five First Principles of LeanSpec
-> Part of spec: [049-leanspec-first-principles](README.md)
-These are the crystal stone rules—the fundamental, unchanging principles that define what LeanSpec is and guide all design decisions.
-## The 5 First Principles
-### 1. Context Economy
-**Specs must fit in working memory—both human and AI.**
-**Why This is Fundamental:**
-- Physics: Context windows are bounded (200K tokens, ~20-30K effective)
-- Biology: Human working memory is 7±2 items
-- Economics: Large contexts cost more in time and money
-- Psychology: Attention is the scarce resource, not storage
-**Quantified Thresholds:**
-- ✅ Target: <300 lines per spec file
-- ⚠️ Warning: 300-400 lines (approaching limit)
-- 🚨 Problem: >400 lines (must split)
-- 🔴 Crisis: >600 lines (definitely split now)
-**Operationalization:**
-- Use sub-specs for complex features
-- Split proactively, not reactively
-- Automated checking: `lean-spec validate --max-lines 400`
-- CI/CD gates for spec complexity
-**How Everything Derives:**
-- Sub-spec files (spec 012) → enables splitting
-- Complexity warnings (spec 048) → enforces limits
-- Flat folder structure → reduces navigation overhead
-- Global sequence numbers → enables easy references
----
-### 2. Signal-to-Noise Maximization
-**Every word must inform decisions or be cut.**
-**Why This is Fundamental:**
-- Token costs penalize verbosity
-- Cognitive load penalizes noise
-- Maintenance costs penalize stale content
-- Clarity enables action
-**The Test:**
-Each sentence must pass: **"What decision does this inform?"**
-If the answer is "none," remove it.
-**What to Cut:**
-- Obvious statements ("software should work correctly")
-- Inferable content (can be derived from context)
-- "Maybe in the future" unless it affects today's design
-- Exhaustive examples when 1-2 would suffice
-- Duplicated information across sections
-**What to Keep:**
-- Decision rationale ("chose X over Y because...")
-- Non-obvious constraints or requirements
-- Success criteria and test conditions
-- Clear problem statements
-- Intent and goals
-**Operationalization:**
-- Review checklist: "Can I remove this without losing clarity?"
-- Peer review focus on unnecessary content
-- AI-assisted verbosity detection
-- Regular pruning of specs
-**How Everything Derives:**
-- "Write only what matters" (README principle)
-- "If it doesn't add clarity, cut it" (AGENTS.md)
-- Skip specs for trivial changes
-- Minimal vs. enterprise templates
----
-### 3. Progressive Disclosure
-**Start simple, add structure only when pain is felt.**
-**Why This is Fundamental:**
-- Teams evolve (solo → small → large)
-- Requirements emerge through building
-- Premature abstraction causes rigidity
-- Conway's Law: Structure mirrors team communication
-**The Evolution Path:**
-**Day 1: Solo Developer**
-```yaml
-status: planned
-created: 2025-11-01
-```
-**Week 2: Small Team**
-```yaml
-status: in-progress
-created: 2025-11-01
-tags: [api, feature]
-priority: high
-```
-**Month 3: Enterprise Needs**
-```yaml
-status: in-progress
-created: 2025-11-01
-tags: [api, feature]
-priority: high
-assignee: alice
-epic: PROJ-123
-reviewer: bob
-sprint: 2025-Q4-S3
-```
-**The Rule:**
-Only add fields/structure when you actively feel pain without them.
-**Pain Indicators:**
-- Can't find relevant specs → Add tags
-- Don't know what to work on next → Add priority/status
-- Unclear ownership → Add assignee
-- Team-specific needs → Add custom fields
-**Anti-Pattern:**
-Adding fields "just in case" or because "enterprise teams might need it."
-**Operationalization:**
-- Templates range from minimal to enterprise
-- Custom fields support team-specific needs
-- No required fields beyond essential metadata
-- "Add complexity only when you feel the pain"
-**How Everything Derives:**
-- Flexible frontmatter system
-- Custom fields
-- Template options (minimal → enterprise)
-- Adaptive structure (README example)
----
-### 4. Intent Over Implementation
-**Capture "why" and "what," let "how" emerge.**
-**Why This is Fundamental:**
-- AI needs intent to make good decisions
-- Implementation details change frequently
-- Unknown unknowns emerge during building
-- Code shows "how," specs should show "why"
-**The Hierarchy:**
-**Must Have (Required):**
-1. **Problem statement** - What are we solving?
-2. **Solution intent** - What's the approach? (high-level)
-3. **Success criteria** - How do we know it works?
-**Should Have (Recommended):**
-1. Design rationale - Why this approach?
-2. Trade-offs considered - What alternatives did we reject?
-3. Key constraints - What limits our options?
-**Could Have (Optional):**
-1. Implementation details - Specific steps
-2. Code examples - Concrete illustrations
-3. Edge cases - Detailed scenarios
-**The Test:**
-- If the spec captures **why** → good
-- If the spec only captures **how** → questionable
-- If the spec captures both **why** and **how** → ideal
-**Living Documentation:**
-- Intent stays relatively stable
-- Implementation evolves as we learn
-- Update specs when understanding changes
-- Incomplete spec > outdated spec
-**Operationalization:**
-- Spec structure: Overview → Design → Plan → Test
-- Overview section must answer "why?"
-- Implementation can be sketchy initially
-- Refine as understanding emerges
-**How Everything Derives:**
-- Standard spec sections (Overview, Design, Plan)
-- Living documentation philosophy
-- Specs evolve with code
-- Focus on outcomes, not prescriptive steps
----
-### 5. Bridge the Gap
-**Specs exist to align human intent with machine execution.**
-**Why This is Fundamental:**
-- Humans think in goals and intent
-- Machines execute in steps and logic
-- Gap must be bridged explicitly
-- Both audiences (human + AI) must understand
-**The Two Audiences:**
-**For Humans:**
-- High-level overview
-- Problem context
-- Design rationale
-- Success criteria
-**For AI:**
-- Unambiguous requirements
-- Clear structure
-- Concrete examples
-- Testable conditions
-**The Bridge:**
-- Overview → provides human context
-- Design → shows the approach
-- Plan → gives machine-readable steps
-- Test → defines objective success
-- Examples → connect abstract to concrete
-**Quality Check:**
-Ask two questions:
-1. **Can a human understand the intent?**
-2. **Can an AI execute the plan?**
-If either answer is "no," the spec needs work.
-**Operationalization:**
-- AI-native from day one (README promise)
-- Works with Cursor, Copilot, Aider
-- MCP server integration
-- AGENTS.md for AI guidance
-- Structured metadata for tooling
-- Examples bridge abstraction gap
-**How Everything Derives:**
-- Structured frontmatter (machine-readable)
-- Clear Overview section (human-readable)
-- CLI tooling (enables automation)
-- MCP server (AI integration)
-- Templates balance both audiences
----
-## Why These 5?
-### Test 1: Never Change ✅
-These principles are derived from immutable constraints:
-- Physics: Context windows are bounded
-- Biology: Human cognition has limits
-- Economics: Time and tokens cost money
-- Reality: Human-AI gap exists
-These constraints won't change (or won't change significantly).
-### Test 2: Everything Derives ✅
-All LeanSpec practices trace back to these principles:
-- Sub-spec files → Context Economy
-- "Write only what matters" → Signal-to-Noise
-- Flexible frontmatter → Progressive Disclosure
-- Overview + Design sections → Intent Over Implementation
-- AI-native design → Bridge the Gap
-### Test 3: Resolve Conflicts ✅
-When two practices conflict, apply principles in priority order:
-1. Context Economy (physics can't be violated)
-2. Signal-to-Noise (every word must earn its keep)
-3. Intent Over Implementation (why before how)
-4. Bridge the Gap (both audiences must understand)
-5. Progressive Disclosure (add structure when needed)
-### Test 4: Define Identity ✅
-A specification is LeanSpec if and only if it:
-- ✅ Fits in working memory (<400 lines per file)
-- ✅ Contains only decision-informing content
-- ✅ Captures intent and success criteria clearly
-- ✅ Can be understood by both humans and AI
-- ✅ Evolves as understanding grows
-### Test 5: Operationalizable ✅
-Each principle can be enforced with concrete mechanisms:
-- Tooling: `lean-spec validate`, `lean-spec health`, `lean-spec split`
-- Culture: Review checklists, team norms, examples
-- Metrics: Track spec length, complexity, update frequency
----
-## Conflict Resolution Framework
-When two practices conflict, apply first principles in order:
-### Priority Order
-1. **Context Economy** - If it doesn't fit in working memory, split it
-2. **Signal-to-Noise** - If it doesn't inform decisions, remove it
-3. **Intent Over Implementation** - Capture why, not just how
-4. **Bridge the Gap** - Both human and AI must understand
-5. **Progressive Disclosure** - Add structure when pain is felt
-### Example Conflicts
-**Conflict 1: "Should I document every edge case?"**
-- Apply: Signal-to-Noise
-- Question: "Does this edge case inform current decisions?"
-- If yes: Document it
-- If no: Skip it (can add later if needed)
-**Conflict 2: "My spec is 450 lines. Should I split it?"**
-- Apply: Context Economy
-- Threshold: >400 lines → split
-- Action: Use sub-specs or simplify
-**Conflict 3: "Should I use custom fields?"**
-- Apply: Progressive Disclosure
-- Question: "Do you feel pain without them?"
-- If no pain yet: Use standard fields
-- If pain: Add custom fields
-**Conflict 4: "Should spec include implementation details?"**
-- Apply: Intent Over Implementation
-- Question: "Does it capture why or just how?"
-- If why: Include it
-- If just how: Make it optional or omit
-**Conflict 5: "Should we create sub-specs upfront for complex feature?"**
-- Apply: Progressive Disclosure + Context Economy
-- Question: "Do you feel the pain yet? Will it exceed 300 lines?"
-- If not yet: Start with single file
-- If yes (or >300 lines expected): Split proactively
----
-## What Makes Something "LeanSpec"?
-### Essential Characteristics
-A specification is LeanSpec if it:
-✅ **Fits in working memory** (<400 lines per file)
-✅ **Contains only decision-informing content** (high signal-to-noise)
-✅ **Captures intent and success criteria clearly** (why + what)
-✅ **Can be understood by both humans and AI** (bridges the gap)
-✅ **Evolves as understanding grows** (living documentation)
-### What LeanSpec Is NOT
-❌ A comprehensive documentation system
-❌ A blueprint that specifies every detail upfront
-❌ A fixed format that all specs must follow
-❌ A replacement for code comments or API docs
-❌ Optimized for humans alone (it's for human + AI)
-### When to Use LeanSpec
-**Use LeanSpec when:**
-- Working with AI coding agents
-- Features span multiple components
-- Design decisions need alignment
-- Context needs to persist across sessions
-- You want lightweight structure that scales
-**Skip LeanSpec when:**
-- Trivial changes (just fix it)
-- Self-explanatory refactors
-- Pure API reference (use code comments + auto-gen)
----
-## Related Documents
-- [Main Spec](README.md) - Overview and complete findings
-- [Analysis](ANALYSIS.md) - Deep dive into constraints and thought experiments
-- [Operationalization](OPERATIONALIZATION.md) - How to enforce these principles