@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/archived/044-spec-relationships-clarity/README.md

@@ -0,0 +1,317 @@
+---
+status: archived
+created: '2025-11-04'
+tags:
+  - ux
+  - clarity
+  - frontmatter
+  - relationships
+  - v0.2.0
+priority: high
+related:
+  - 043-official-launch-02
+created_at: '2025-11-04T00:00:00Z'
+updated_at: '2025-11-11T04:26:08.272Z'
+completed_at: '2025-11-06T06:35:03.913Z'
+completed: '2025-11-06'
+transitions:
+  - status: complete
+    at: '2025-11-06T06:35:03.913Z'
+  - status: archived
+    at: '2025-11-11T04:26:08.272Z'
+---
+
+# Clarify Spec Relationship Model
+
+> **Status**: 📦 Archived · **Priority**: High · **Created**: 2025-11-04 · **Tags**: ux, clarity, frontmatter, relationships, v0.2.0
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Problem**: The current spec relationship model is confusing and inconsistent.
+
+**Confusion points:**
+1. **`related` appears bidirectional but isn't** - If spec A has `related: [B]`, the `deps` command shows it from A's perspective but not automatically from B's
+2. **`depends_on` vs `related` unclear** - When should you use which?
+3. **Display confusion** - "Related" vs "Related By" sections in `lean-spec deps` output
+4. **Symmetry expectations** - Users expect `related` to be symmetric (if A relates to B, then B relates to A)
+
+**Current behavior:**
+```bash
+# Spec 042 has: related: [043]
+lean-spec deps 042  # Shows: Related → 043
+lean-spec deps 043  # Shows: Related By ← 042  (had to add this!)
+```
+
+**Why this matters:**
+- Core UX issue affecting how users track work
+- Confusion leads to inconsistent spec relationships
+- Critical for v0.2.0 launch coordination (blocking specs need clear relationships)
+
+## Design
+
+### Option 1: Make `related` Truly Bidirectional (Recommended)
+
+**Change behavior**: When spec A has `related: [B]`, automatically show the relationship from both sides without requiring B to also list A.
+
+**Implementation:**
+- `related` field means "this spec is related to these specs" (one-way declaration)
+- `lean-spec deps` shows bidirectional view automatically
+- Remove "Related" vs "Related By" distinction - just show "Related Specs"
+- Merge both directions into single list
+
+**Example:**
+```yaml
+# Spec 042
+related: [043]
+
+# Spec 043
+related: []  # Doesn't need to list 042
+```
+
+**Output:**
+```bash
+lean-spec deps 042
+Related Specs:
+  ⟷ 043-official-launch-02 [in-progress]
+
+lean-spec deps 043
+Related Specs:
+  ⟷ 042-mcp-error-handling [in-progress]  # Automatically shown!
+```
+
+**Pros:**
+- ✅ Intuitive - matches user expectations
+- ✅ Less redundancy - don't need to update both specs
+- ✅ Cleaner UX - single "Related Specs" section
+- ✅ Easier maintenance - update in one place
+
+**Cons:**
+- ❌ Can't distinguish who declared the relationship
+- ❌ Asymmetric data model (one side declares, both show)
+
+### Option 2: Keep Directional, Improve Clarity
+
+**Change terminology and documentation:**
+- Rename `related` → `see-also` or `references`
+- Make it clear this is **directional** (one-way)
+- Better docs explaining when to use each field
+
+**Relationship types:**
+```yaml
+depends_on: [spec-id]  # Hard dependency - can't start until these complete
+see_also: [spec-id]    # Soft reference - related context, no blocking
+blocks: [spec-id]      # This spec blocks these specs (inverse of depends_on)
+```
+
+**Pros:**
+- ✅ Clear semantics
+- ✅ Explicit control over directionality
+- ✅ More powerful for complex relationships
+
+**Cons:**
+- ❌ More fields to understand
+- ❌ More manual work to maintain relationships
+- ❌ Still confusing for simple use cases
+
+### Option 3: Bidirectional with Explicit Sync
+
+**Introduce relationship commands:**
+```bash
+lean-spec relate 042 043      # Links both specs bidirectionally
+lean-spec unrelate 042 043    # Removes from both
+lean-spec deps 042 --sync     # Auto-sync relationships
+```
+
+**Implementation:**
+- Commands automatically update both specs
+- Maintain bidirectional consistency
+- Can still manually edit for asymmetric cases
+
+**Pros:**
+- ✅ Best of both worlds - bidirectional when desired
+- ✅ Still allows manual asymmetric relationships
+- ✅ Tooling enforces consistency
+
+**Cons:**
+- ❌ More commands to learn
+- ❌ More complex implementation
+- ❌ Risk of conflicts in concurrent edits
+
+### Option 4: Typed Relationships (Advanced)
+
+**Introduce relationship types:**
+```yaml
+relationships:
+  - spec: 043
+    type: part-of       # This spec is part of 043
+  - spec: 018
+    type: prerequisite  # 018 should be done first
+  - spec: 037
+    type: related       # Loosely related
+```
+
+**Pros:**
+- ✅ Very expressive
+- ✅ Clear semantics
+- ✅ Supports complex project structures
+
+**Cons:**
+- ❌ Too complex for most users
+- ❌ Against "lean" philosophy
+- ❌ Overkill for 90% of use cases
+
+## Recommendation
+
+**Go with Option 1: Make `related` truly bidirectional**
+
+**Rationale:**
+1. **Matches user expectations** - "related" sounds symmetric
+2. **Lean philosophy** - simpler is better
+3. **Reduces maintenance** - update once, show everywhere
+4. **Backward compatible** - existing specs still work
+
+**Keep directional for dependencies:**
+- `depends_on` stays directional (hard dependency)
+- `related` becomes bidirectional (soft relationship)
+- This gives us both semantic clarity and ease of use
+
+## Plan
+
+### Phase 1: Update `deps` Command UX ⏳ READY TO IMPLEMENT
+- [ ] Merge "Related" and "Related By" into single "Related Specs" section
+- [ ] Show relationships bidirectionally without distinction
+- [ ] Update help text and examples
+- [ ] Test with launch specs (042, 037, 043, etc.)
+
+**Implementation Notes (2025-11-04):**
+- Current `deps` command shows "Related" and "Related By" separately
+- Bidirectional approach is intuitive and reduces maintenance
+- Low risk, high value UX improvement
+- Estimated: 2-4 hours implementation
+- Can implement independently, no blocking dependencies
+
+### Phase 2: Update Documentation
+- [ ] Update AGENTS.md to explain relationship model
+- [ ] Update command docs to clarify `depends_on` vs `related`
+- [ ] Add examples showing both types
+- [ ] Document: "related = bidirectional, depends_on = directional blocking"
+
+### Phase 3: Consider Enhanced Commands (Optional)
+- [ ] Add `lean-spec relate <spec-a> <spec-b>` convenience command
+- [ ] Add `lean-spec unrelate <spec-a> <spec-b>` 
+- [ ] Consider `--sync` flag to auto-update both sides
+- [ ] Defer if not needed for v0.2.0
+
+### Phase 4: Visual Improvements
+- [ ] Consider showing relationship direction for `depends_on`
+- [ ] Use better symbols: → for depends, ⟷ for related
+- [ ] Add color coding for relationship types
+- [ ] Test with complex dependency graphs
+
+## Test
+
+### Bidirectional Behavior
+- [ ] Spec A has `related: [B]`, `lean-spec deps A` shows B
+- [ ] `lean-spec deps B` also shows A (bidirectional)
+- [ ] Spec C has `depends_on: [D]`, shows directionally only
+- [ ] `lean-spec deps D` shows "Blocks: C" (inverse)
+- [ ] Combined test: A related to B, A depends on C
+
+### UX Clarity
+- [ ] Users understand difference between `related` and `depends_on`
+- [ ] No confusion about "Related" vs "Related By"
+- [ ] Single section makes sense to first-time users
+- [ ] Help text is clear and accurate
+
+### Edge Cases
+- [ ] Spec relates to archived spec
+- [ ] Spec relates to non-existent spec (graceful error)
+- [ ] Circular relationships (A → B → A)
+- [ ] Large relationship graphs (performance)
+
+### Migration
+- [ ] Existing specs with `related` continue working
+- [ ] No breaking changes to frontmatter format
+- [ ] JSON output includes both directions
+- [ ] MCP server reflects new behavior
+
+## Notes
+
+### Current State Analysis
+
+**What we have now:**
+```typescript
+// In spec 042
+related: [043]
+
+// Command output is asymmetric:
+lean-spec deps 042  // Related: 043
+lean-spec deps 043  // Related By: 042
+```
+
+**The confusion:**
+- "Related" sounds mutual/bidirectional
+- But it's stored directionally (only in 042)
+- We had to add "Related By" to show reverse direction
+- This creates two sections for what feels like one relationship
+
+### Semantic Comparison
+
+| Field | Current Behavior | Proposed Behavior |
+|-------|-----------------|-------------------|
+| `depends_on` | Directional blocking dependency | **Keep**: Directional - A depends on B (B blocks A) |
+| `related` | Directional soft reference | **Change**: Bidirectional - A relates to B means B relates to A |
+| Display | "Related" + "Related By" sections | **Merge**: Single "Related Specs" section |
+
+### Implementation Impact
+
+**Code changes:**
+- Update `findRelated()` to merge both directions
+- Remove "Related By" section
+- Update JSON output to include both directions in `related` field
+- Update tests
+
+**Estimated effort:** 2-4 hours
+
+**Risk:** Low - backward compatible, improves UX
+
+### Alternative: Do Nothing
+
+**Could argue:**
+- Current behavior is technically correct
+- Users can learn "Related" vs "Related By"
+- Already implemented and working
+
+**Counter-argument:**
+- UX matters more than technical correctness
+- If it's confusing, fix it
+- Better now than after wider adoption
+- Aligns with "lean" philosophy of clarity
+
+### Related Work
+
+- Spec 043: Official Launch - needs clear relationship tracking
+- Spec 018: Spec Validation - could validate relationship consistency
+- Spec 037: Docs Overhaul - should document relationship model clearly
+
+### Open Questions
+
+1. **Should `lean-spec relate` command auto-edit both specs?**
+   - Pro: Maintains consistency
+   - Con: More complex, can wait for v0.3.0
+
+2. **How to handle `depends_on` in visualization?**
+   - Keep separate from `related`? Yes
+   - Show direction with arrows? Yes (→ for depends, ⟷ for related)
+
+3. **Should related specs show in board/list views?**
+   - Probably not - would clutter
+   - Keep in `deps` command only
+
+4. **What about `blocks` field?**
+   - Auto-computed from `depends_on` (inverse)
+   - Don't need explicit field
+   - Current behavior is correct

package/.next/standalone/packages/ui/dist/standalone/specs/archived/046-stats-dashboard-refactor/DESIGN.md

@@ -0,0 +1,276 @@
+# Design: Stats & Dashboard Reorganization
+
+## Command Redesign
+
+### Part 1: Rename `analytics` → `stats`
+
+**Why "stats" over "analytics"?**
+- Shorter, easier to type
+- More intuitive for quick metrics
+- Matches common CLI patterns (`git stats`, `npm stats`)
+- Less intimidating for non-technical PMs
+
+**Implementation:**
+1. Merge `src/commands/analytics.ts` logic into `src/commands/stats.ts`
+2. Delete `src/commands/analytics.ts` entirely
+3. Update command registration in `cli.ts`
+4. Remove analytics from help text
+5. Keep all analytics functionality (just rename command)
+
+**Breaking Change (v0.2.0):**
+- `lean-spec analytics` removed → use `lean-spec stats`
+- Note in CHANGELOG as breaking change
+- Update all documentation immediately
+
+### Part 2: Simplify Default Stats Output
+
+**Current Problem**: `lean-spec stats` shows everything (status, priority, tags, timeline, velocity)
+- Too much info for quick check-ins
+- Takes time to render
+- Overwhelming for PMs
+
+**New Default Output** (`lean-spec stats`):
+```
+📊 Spec Stats
+
+📈 Overview
+  Total Specs           42
+  Active (Planned+WIP)  20
+  Complete              15
+  Health Score          73% ✓
+
+📊 Status
+  📅 Planned       ████░░░░  5
+  ⏳ In Progress   ████████  15
+  ✅ Complete      ██████░░  10
+
+🎯 Priority Focus
+  🔴 Critical      2 specs (1 overdue!)
+  🟠 High          5 specs (3 in-progress)
+
+⚠️  Needs Attention
+  • spec-042: Critical bug overdue by 2 days
+  • 5 specs in-progress > 7 days
+
+🚀 Velocity Summary
+  Avg Cycle Time   5.2 days ✓ (target: 7d)
+  Throughput       2.8/week ↑
+  WIP              5 specs
+
+💡 Use `lean-spec stats --full` for detailed analytics
+```
+
+**Key Changes:**
+- **Focus on actionable insights** - What needs attention?
+- **Health score** - Simple completion rate (% complete)
+- **Priority focus** - Only show priorities that matter (critical/high with issues)
+- **Needs attention** - Top 3-5 actionable items
+- **Velocity summary** - Key metrics only (not full breakdown)
+- **Clear next action** - Prompt for `--full` if they want more
+
+**Full Stats Output** (`lean-spec stats --full`):
+- Everything from current analytics command
+- Stats + Timeline + Velocity (all sections)
+- Equivalent to current `lean-spec analytics` output
+
+### Part 3: Integrate Smart Insights into Stats
+
+**Current**: Smart insights in dashboard, velocity in analytics (separated)
+**New**: Both unified in stats command
+
+**Smart Insights Algorithm** (for "Needs Attention"):
+1. **Critical overdue** - `priority=critical, due < today, status != complete`
+2. **High overdue** - `priority=high, due < today, status != complete`
+3. **Long-running WIP** - `status=in-progress, updated > 7 days ago`
+4. **Blocked specs** - Has dependencies but can't start
+5. **Critical not started** - `priority=critical, status=planned`
+
+Show top 5 items, then "and N more need attention"
+
+**Velocity Integration:**
+- Include velocity summary in default stats
+- Full velocity breakdown in `--full` or `--velocity`
+- Make velocity calculations part of core stats logic
+
+### Part 4: Enhance Board with Health Summary
+
+**Why**: Board is the primary PM/workflow entry point - should provide context
+
+**New Board Output:**
+```
+📋 Spec Kanban Board
+
+╔══════════════════════════════════════════════════════════╗
+║  Project Health                                          ║
+║  42 total · 20 active · 15 complete · 73% health         ║
+║  ⚠️  2 critical overdue · 5 specs WIP > 7 days           ║
+║  🚀 Velocity: 5.2d avg cycle · 2.8/wk throughput         ║
+╚══════════════════════════════════════════════════════════╝
+
+📅 Planned (5)
+  🔴 Critical (2)
+    spec-048-critical-bug           @alice  #bug #launch
+    spec-047-security-patch         @bob    #security
+  🟠 High (3)
+    spec-046-stats-refactor         @alice  #ux #refactor
+    ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⏳ In Progress (15)
+  🔴 Critical (1)
+    spec-042-error-handling         @alice  #bug  (8d ⚠️ long)
+  ...
+```
+
+**Health Summary Box Shows:**
+- **Totals** - Quick counts
+- **Health score** - Simple % complete
+- **Alerts** - Critical issues needing attention
+- **Velocity snapshot** - Key metrics only
+
+**Options:**
+- `lean-spec board` - Default (with health summary)
+- `lean-spec board --simple` - Original kanban-only view (no health box)
+- `lean-spec board --health-only` - Just show health box, no kanban
+
+**Implementation:**
+- Extract health calculation to `utils/health.ts`
+- Reuse velocity calculations from stats
+- Keep board rendering clean (separate concerns)
+
+### Part 5: Remove Dashboard Command
+
+**Why Remove?**
+- With enhanced board + simplified stats, dashboard is redundant
+- Users can get overview from `lean-spec board`
+- Detailed analytics from `lean-spec stats --full`
+- Reduces command sprawl
+
+**Migration Path:**
+```
+lean-spec dashboard              → lean-spec board
+lean-spec dashboard --compact    → lean-spec board --health-only
+lean-spec dashboard --json       → lean-spec stats --json
+```
+
+**Removal Strategy (v0.2.0):**
+- Delete `src/commands/dashboard.ts` entirely
+- Remove from CLI registration
+- Update all documentation
+- Note in CHANGELOG as breaking change
+
+## Architecture
+
+**New File Structure:**
+```
+src/commands/
+  ├── stats.ts           # ENHANCED: Unified stats + velocity + insights
+  ├── board.ts           # ENHANCED: Kanban + health summary
+  └── ...                # analytics.ts and dashboard.ts DELETED
+
+src/utils/
+  ├── health.ts          # NEW: Health score calculation
+  ├── velocity.ts        # KEEP: Velocity metrics (used by stats)
+  ├── insights.ts        # NEW: Smart insights algorithm
+  └── spec-stats.ts      # KEEP: Basic counting/grouping
+```
+
+## Health Score Calculation
+
+`utils/health.ts`:
+```typescript
+export interface HealthMetrics {
+  score: number;           // 0-100
+  totalSpecs: number;
+  activeSpecs: number;
+  completeSpecs: number;
+  criticalIssues: string[];
+  warnings: string[];
+}
+
+export function calculateHealth(specs: SpecInfo[]): HealthMetrics {
+  // Simple: completion_rate = complete / total * 100
+  
+  let completeCount = 0;
+  let completeWeight = 0;
+  const criticalIssues: string[] = [];
+  const warnings: string[] = [];
+  
+  for (const spec of specs) {
+    const weight = priorityWeight(spec.frontmatter.priority);
+    totalWeight += weight;
+    
+    if (spec.frontmatter.status === 'complete') {
+      completeWeight += weight;
+    }
+    
+    // Detect critical issues
+    if (isCriticalOverdue(spec)) {
+      criticalIssues.push(spec.path);
+    }
+    if (isLongRunning(spec)) {
+      warnings.push(spec.path);
+    }
+  }
+  
+  return {
+    score: Math.round((completeWeight / totalWeight) * 100),
+    totalSpecs: specs.length,
+    activeSpecs: specs.filter(s => ['planned', 'in-progress'].includes(s.frontmatter.status)).length,
+    completeSpecs: specs.filter(s => s.frontmatter.status === 'complete').length,
+    criticalIssues,
+    warnings,
+  };
+}
+```
+
+## Smart Insights
+
+`utils/insights.ts`:
+```typescript
+export interface Insight {
+  severity: 'critical' | 'warning' | 'info';
+  message: string;
+  specs: string[];
+}
+
+export function generateInsights(specs: SpecInfo[]): Insight[] {
+  const insights: Insight[] = [];
+  
+  // 1. Critical overdue
+  const criticalOverdue = specs.filter(s => 
+    s.frontmatter.priority === 'critical' &&
+    s.frontmatter.due && dayjs(s.frontmatter.due).isBefore(dayjs()) &&
+    s.frontmatter.status !== 'complete'
+  );
+  
+  if (criticalOverdue.length > 0) {
+    insights.push({
+      severity: 'critical',
+      message: `${criticalOverdue.length} critical specs overdue`,
+      specs: criticalOverdue.map(s => s.path),
+    });
+  }
+  
+  // 2. Long-running WIP
+  const longRunning = specs.filter(s =>
+    s.frontmatter.status === 'in-progress' &&
+    s.frontmatter.updated &&
+    dayjs().diff(dayjs(s.frontmatter.updated), 'day') > 7
+  );
+  
+  if (longRunning.length > 0) {
+    insights.push({
+      severity: 'warning',
+      message: `${longRunning.length} specs in-progress > 7 days`,
+      specs: longRunning.map(s => s.path),
+    });
+  }
+  
+  // 3. Critical not started
+  // ... more insight rules
+  
+  return insights.slice(0, 5); // Top 5 only
+}
+```