agileflow 2.77.0 → 2.79.0

package/src/core/commands/ideate.md

@@ -0,0 +1,446 @@
+---
+description: Generate categorized improvement ideas using multi-expert analysis
+argument-hint: [SCOPE=all|security|perf|code|ux] [DEPTH=quick|deep] [OUTPUT=report|stories|both]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ideate - Ideation orchestrator with multi-expert analysis"
+    - "CRITICAL: Deploy experts IN PARALLEL in ONE message with multiple Task calls"
+    - "CRITICAL: Wait for all results before synthesis (use TaskOutput with block=true)"
+    - "CRITICAL: Confidence scoring: HIGH (2+ experts agree) | MEDIUM (1 expert with evidence) | LOW (vague, exclude)"
+    - "MUST parse arguments: SCOPE (all/security/perf/code/ux) | DEPTH (quick/deep) | OUTPUT (report/stories/both)"
+    - "MUST categorize by domain: Security, Performance, Code Quality, UX, Testing, API/Architecture"
+    - "MUST estimate effort for each idea: High/Medium/Low impact"
+    - "Optional: Generate stories for HIGH-confidence items (if OUTPUT=stories or both)"
+  state_fields:
+    - scope
+    - depth
+    - output_mode
+    - selected_experts
+    - ideas_generated
+---
+
+# /agileflow:ideate
+
+Deploy multiple domain experts in parallel to generate categorized improvement suggestions for your codebase. Inspired by AutoClaude's ideation feature.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js ideate
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ideate` - Generate improvement ideas via multi-expert analysis
+
+**Quick Usage**:
+```
+/agileflow:ideate SCOPE=all DEPTH=quick OUTPUT=report
+```
+
+**What It Does**: Deploy 4-6 domain experts → Each generates 3-5 ideas → Synthesize with confidence scoring → Categorized report
+
+**Arguments**:
+- `SCOPE=all|security|perf|code|ux` (default: all)
+- `DEPTH=quick|deep` (default: quick)
+- `OUTPUT=report|stories|both` (default: report)
+
+### Tool Usage Examples
+
+**Task** (deploy expert in parallel):
+```xml
+<invoke name="Task">
+<parameter name="description">Security ideation analysis</parameter>
+<parameter name="prompt">Generate 3-5 specific improvement ideas for this codebase from a SECURITY perspective...</parameter>
+<parameter name="subagent_type">agileflow-security</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+```
+
+**TaskOutput** (collect results):
+```xml
+<invoke name="TaskOutput">
+<parameter name="task_id">{id}</parameter>
+<parameter name="block">true</parameter>
+</invoke>
+```
+
+**Write** (save report):
+```xml
+<invoke name="Write">
+<parameter name="file_path">/path/to/docs/08-project/ideation-YYYYMMDD.md</parameter>
+<parameter name="content"># Ideation Report...</parameter>
+</invoke>
+```
+
+**AskUserQuestion** (next steps):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "What would you like to do with these ideas?", "header": "Next Steps", "multiSelect": false, "options": [{"label": "Create stories for high-confidence items", "description": "Generate stories in docs/06-stories/"}, {"label": "Create epic grouping all improvements", "description": "Bundle into a new epic"}, {"label": "Save report and done", "description": "Just keep the report"}]}]</parameter>
+</invoke>
+```
+
+**Categories**: Security, Performance, Code Quality, UX/Design, Testing, API/Architecture
+**Confidence**: High (2+ experts agree), Medium (1 expert with evidence)
+**Output**: `docs/08-project/ideation-<YYYYMMDD>.md` | Optional stories
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    USER: /agileflow:ideate                  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│              IDEATION ORCHESTRATOR                          │
+│  1. Parse SCOPE to determine which experts                  │
+│  2. Deploy 4-6 experts IN PARALLEL                          │
+│  3. Each expert generates 3-5 improvement ideas             │
+│  4. Collect and synthesize with confidence scoring          │
+│  5. Generate categorized report                             │
+└─────────────────────────────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        ▼                   ▼                   ▼
+┌───────────┐       ┌───────────┐       ┌───────────┐
+│  Security │       │Performance│       │  Refactor │
+│  Expert   │       │  Expert   │       │  Expert   │
+│           │       │           │       │           │
+│ 3-5 ideas │       │ 3-5 ideas │       │ 3-5 ideas │
+└───────────┘       └───────────┘       └───────────┘
+        │                   │                   │
+        └───────────────────┼───────────────────┘
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   SYNTHESIS ENGINE                          │
+│  • Find overlapping ideas (HIGH CONFIDENCE)                 │
+│  • Flag unique insights with evidence (MEDIUM)              │
+│  • Discard vague suggestions (excluded)                     │
+│  • Categorize by domain                                     │
+│  • Estimate effort for each idea                            │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   IDEATION REPORT                           │
+│  📊 Total Ideas: X (High: Y, Medium: Z)                     │
+│  🎯 High-Confidence Improvements (agreed by 2+ experts)     │
+│  💡 Medium-Confidence Opportunities (single expert)         │
+│  📋 Suggested Stories (if OUTPUT=stories)                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Prompt
+
+ROLE: Ideation Orchestrator
+
+You coordinate multiple domain experts to generate improvement suggestions for the codebase, then synthesize their findings into a prioritized, actionable report.
+
+### STEP 1: PARSE ARGUMENTS
+
+Parse the input arguments:
+
+**SCOPE** (which experts to deploy):
+| SCOPE | Experts |
+|-------|---------|
+| `all` (default) | security, performance, refactor, ui, testing, api (6 experts) |
+| `security` | security, api, testing (3 experts) |
+| `perf` | performance, database, api (3 experts) |
+| `code` | refactor, testing, api (3 experts) |
+| `ux` | ui, accessibility, api (3 experts) |
+
+**DEPTH**:
+- `quick` (default): Each expert generates 3 ideas, focuses on high-impact only
+- `deep`: Each expert generates 5 ideas, includes lower-priority items
+
+**OUTPUT**:
+- `report` (default): Generate ideation report only
+- `stories`: Generate stories for high-confidence items
+- `both`: Report + stories
+
+### STEP 2: DEPLOY EXPERTS IN PARALLEL
+
+**CRITICAL**: Deploy ALL experts in a SINGLE message with multiple Task tool calls.
+
+Use this prompt template for each expert:
+
+```
+EXPERTISE FIRST: Read your expertise.yaml file if it exists at packages/cli/src/core/experts/{domain}/expertise.yaml
+
+TASK: Generate {3|5} specific, actionable improvement ideas for this codebase from your {DOMAIN} perspective.
+
+DEPTH: {quick|deep}
+
+For each idea, provide:
+1. **Title**: Concise name (5-10 words)
+2. **Category**: Your domain (Security/Performance/Code Quality/UX/Testing/API)
+3. **Impact**: High/Medium/Low
+4. **Effort**: Hours/Days/Weeks
+5. **Files**: Specific file paths affected
+6. **Why**: One sentence on why this matters
+7. **Approach**: Brief implementation approach (2-3 sentences)
+
+RULES:
+- Be SPECIFIC with file paths - no vague suggestions
+- Only suggest improvements you can VERIFY exist in the codebase
+- Prioritize by impact (High first)
+- For "quick" depth, focus only on High/Medium impact items
+- Include evidence (code patterns, metrics, file paths)
+
+FORMAT each idea as:
+---
+### {Title}
+**Category**: {domain} | **Impact**: {High/Medium/Low} | **Effort**: {estimate}
+**Files**: `{path1}`, `{path2}`
+**Why**: {reason}
+**Approach**: {brief approach}
+---
+```
+
+**Example deployment for SCOPE=all**:
+
+```xml
+<invoke name="Task">
+<parameter name="description">Security ideation</parameter>
+<parameter name="prompt">[prompt with domain=security]</parameter>
+<parameter name="subagent_type">agileflow-security</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Performance ideation</parameter>
+<parameter name="prompt">[prompt with domain=performance]</parameter>
+<parameter name="subagent_type">agileflow-performance</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Code quality ideation</parameter>
+<parameter name="prompt">[prompt with domain=refactor/code quality]</parameter>
+<parameter name="subagent_type">agileflow-refactor</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">UX ideation</parameter>
+<parameter name="prompt">[prompt with domain=ui/ux]</parameter>
+<parameter name="subagent_type">agileflow-ui</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">Testing ideation</parameter>
+<parameter name="prompt">[prompt with domain=testing]</parameter>
+<parameter name="subagent_type">agileflow-testing</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+
+<invoke name="Task">
+<parameter name="description">API/Architecture ideation</parameter>
+<parameter name="prompt">[prompt with domain=api/architecture]</parameter>
+<parameter name="subagent_type">agileflow-api</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+```
+
+### STEP 3: COLLECT RESULTS
+
+Wait for all experts to complete:
+
+```xml
+<invoke name="TaskOutput">
+<parameter name="task_id">{security_id}</parameter>
+<parameter name="block">true</parameter>
+</invoke>
+
+<invoke name="TaskOutput">
+<parameter name="task_id">{performance_id}</parameter>
+<parameter name="block">true</parameter>
+</invoke>
+<!-- ... collect all expert results ... -->
+```
+
+### STEP 4: SYNTHESIZE RESULTS
+
+Analyze all expert ideas and synthesize:
+
+**Confidence Scoring**:
+
+| Confidence | Criteria | Action |
+|------------|----------|--------|
+| **HIGH** | 2+ experts suggest similar idea | Include prominently, recommend immediate action |
+| **MEDIUM** | 1 expert with specific evidence (file paths, metrics) | Include as opportunity |
+| **LOW** | 1 expert, vague/no evidence | Exclude from report |
+
+**Overlap Detection**:
+- Ideas about the same file/component from different experts = HIGH confidence
+- Ideas with similar titles/approaches = potential overlap, merge
+- Unique insights with evidence = valuable MEDIUM confidence
+
+**Categorization**:
+Group final ideas by category:
+- 🔒 Security
+- ⚡ Performance
+- 🧹 Code Quality
+- 🎨 UX/Design
+- 🧪 Testing
+- 🏗️ API/Architecture
+
+### STEP 5: GENERATE OUTPUT
+
+**Report Format**:
+
+```markdown
+# Ideation Report
+
+**Generated**: {YYYY-MM-DD}
+**Scope**: {scope}
+**Depth**: {quick|deep}
+**Experts Consulted**: {list of experts}
+**Total Ideas**: {X} (High-Confidence: {Y}, Medium-Confidence: {Z})
+
+---
+
+## 🎯 High-Confidence Improvements
+*Agreed by multiple experts - prioritize these*
+
+### 1. {Title}
+**Category**: {category} | **Impact**: High | **Effort**: {estimate}
+**Experts**: {expert1}, {expert2}
+**Files**: `{path1}`, `{path2}`
+**Why**: {reason}
+**Approach**: {brief approach}
+
+### 2. {Title}
+...
+
+---
+
+## 💡 Medium-Confidence Opportunities
+*Single expert with evidence - worth exploring*
+
+### {N}. {Title}
+**Category**: {category} | **Impact**: {level} | **Effort**: {estimate}
+**Expert**: {expert}
+**Files**: `{path}`
+**Why**: {reason}
+**Approach**: {brief approach}
+
+---
+
+## 📊 Summary by Category
+
+| Category | High | Medium | Total |
+|----------|------|--------|-------|
+| 🔒 Security | X | Y | Z |
+| ⚡ Performance | X | Y | Z |
+| 🧹 Code Quality | X | Y | Z |
+| ... | | | |
+
+---
+
+## 📋 Recommended Next Steps
+
+1. Address high-confidence security items first
+2. Schedule performance improvements for next sprint
+3. Add code quality items to tech debt backlog
+```
+
+**Save report to**: `docs/08-project/ideation-{YYYYMMDD}.md`
+
+### STEP 6: STORY GENERATION (if OUTPUT=stories or both)
+
+For each HIGH-confidence idea, generate a story:
+
+```markdown
+---
+story_id: US-XXXX
+type: improvement
+ideation_source: ideation-{YYYYMMDD}.md
+estimate: {effort}
+---
+
+# US-XXXX: {Idea Title}
+
+## Background
+Identified in ideation report from {date}. Agreed by: {experts}.
+
+## Acceptance Criteria
+- [ ] {specific criterion based on approach}
+- [ ] {criterion}
+- [ ] Tests pass
+
+## Technical Notes
+{approach from ideation}
+
+## Files to Modify
+- `{path1}`
+- `{path2}`
+```
+
+### STEP 7: OFFER NEXT STEPS
+
+After generating output, present options:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do with these ideas?",
+  "header": "Next Steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Create stories for high-confidence items", "description": "Generate stories in docs/06-stories/"},
+    {"label": "Create epic grouping all improvements", "description": "Bundle into EP-XXXX: Ideation Improvements"},
+    {"label": "Run deeper analysis on specific category", "description": "Re-run with SCOPE={category} DEPTH=deep"},
+    {"label": "Save report and done", "description": "Keep the report, no further action"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Example Execution
+
+**User**: `/agileflow:ideate SCOPE=all DEPTH=quick OUTPUT=report`
+
+**Step 1**: Parse → SCOPE=all (6 experts), DEPTH=quick (3 ideas each), OUTPUT=report
+
+**Step 2**: Deploy 6 experts in parallel
+
+**Step 3**: Collect results (~18 raw ideas)
+
+**Step 4**: Synthesize:
+- 4 ideas mentioned by 2+ experts → HIGH confidence
+- 8 ideas with specific evidence → MEDIUM confidence
+- 6 ideas too vague → excluded
+
+**Step 5**: Generate report with 12 ideas, saved to `docs/08-project/ideation-20260106.md`
+
+**Step 6**: Skipped (OUTPUT=report only)
+
+**Step 7**: Present next steps via AskUserQuestion
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| SCOPE | all, security, perf, code, ux | all | Which domains to analyze |
+| DEPTH | quick, deep | quick | Number of ideas per expert (3 vs 5) |
+| OUTPUT | report, stories, both | report | What to generate |
+
+{{argument}}

package/src/core/commands/impact.md

@@ -1,6 +1,22 @@
 ---
 description: Analyze change impact across codebase
 argument-hint: [FILES=<paths>] [BASE=<branch>] [RUN_TESTS=yes|no]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Auto-detect changed files from git diff if FILES not specified"
+    - "Build dependency graph: direct + indirect imports (2 levels max)"
+    - "Find related tests: unit, integration, E2E (pattern matching + coverage mapping)"
+    - "Detect breaking changes (function signature changes, type modifications)"
+    - "Calculate risk scores: critical (impact now) / recommended (test anyway) / optional (low risk)"
+    - "Show affected files with line numbers of callers"
+    - "Generate clear impact report with actionable test recommendations"
+    - "Optionally run affected tests (RUN_TESTS=yes default if tests found)"
+  state_fields:
+    - changed_files_count
+    - affected_files_count
+    - tests_to_run_count
+    - breaking_changes_detected
 ---
 
 # impact-analysis

package/src/core/commands/metrics.md

@@ -1,7 +1,23 @@
 ---
 description: Analytics dashboard with cycle time and throughput
-argument-hint: [TIMEFRAME=7d|30d|90d|all] [EPIC=<id>] [OWNER=<id>] [FORMAT=ascii|json|csv] [METRIC=cycle-time|lead-time|throughput|all]
+argument-hint: "[TIMEFRAME=7d|30d|90d|all] [EPIC=<id>] [OWNER=<id>] [FORMAT=ascii|json|csv] [METRIC=cycle-time|lead-time|throughput|all]"
 model: haiku
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:metrics - Metrics & analytics specialist (read-only)"
+    - "MUST read docs/09-agents/bus/log.jsonl (parse all lifecycle events)"
+    - "MUST read docs/09-agents/status.json (current state, WIP, owners)"
+    - "MUST calculate 10+ metrics: cycle-time, lead-time, throughput, WIP, utilization, epic-health, estimation, blockers, flow-efficiency, CFD"
+    - "MUST show trends (↗ ↘ →) with % change compared to previous period"
+    - "MUST use health indicators (🟢🟡🔴) for quick status assessment"
+    - "MUST provide actionable recommendations based on data"
+    - "MUST always include timeframe and generation timestamp"
+  state_fields:
+    - timeframe
+    - metric_type
+    - format
+    - epic_filter
 ---
 
 # metrics
@@ -22,51 +38,139 @@ Comprehensive project analytics dashboard with cycle time, lead time, throughput
 
 <!-- COMPACT_SUMMARY_START -->
 
-## Compact Summary
+## ⚠️ COMPACT SUMMARY - /agileflow:metrics IS ACTIVE
 
-**Role**: Metrics & Analytics Specialist
+**CRITICAL**: You are the Metrics Specialist. This command provides data-driven analytics (read-only).
 
-**Purpose**: Generate comprehensive project analytics from AgileFlow data sources to enable data-driven decision making and identify process improvements.
+---
 
-**Data Sources**:
-- `docs/09-agents/bus/log.jsonl` - Event stream with timestamps for lifecycle events
-- `docs/09-agents/status.json` - Current state of all stories
-- `docs/06-stories/**/US-*.md` - Story metadata and frontmatter
-- `docs/05-epics/*.md` - Epic-level data
+### 🚨 RULE #1: ALWAYS Calculate From Raw Data
 
-**Core Metrics**: Cycle Time, Lead Time, Throughput, WIP, Agent Utilization, Epic Health, Estimation Accuracy, Blocked Story Analysis, Flow Efficiency, Cumulative Flow
+- Read docs/09-agents/bus/log.jsonl (lifecycle events)
+- Read docs/09-agents/status.json (current state)
+- Never assume or estimate (calculate from data)
+- Show all source timestamps and calculations
 
-**Critical Behavioral Rules**:
-- Calculate from raw data sources, never assume or estimate
-- Show trends (↗↘) compared to previous period
-- Use health indicators (🟢🟡🔴) for quick status assessment
-- Provide actionable recommendations based on data
-- Always include timeframe and generation timestamp
+### 🚨 RULE #2: ALWAYS Show Trends With Comparison
 
-**Input Parameters**:
-- `TIMEFRAME`: 7d|30d|90d|all (default: 30d)
-- `EPIC`: Filter by specific epic ID
-- `OWNER`: Filter by agent/owner ID
-- `FORMAT`: ascii|markdown|json|csv (default: ascii)
-- `METRIC`: cycle-time|lead-time|throughput|all (default: all)
-
-**Workflow**:
-1. Parse input parameters → Load data from bus/log.jsonl and status.json
-2. Calculate metrics using timestamps → Compute statistics (avg, median, p85, trends)
-3. Generate visualizations (ASCII bars, distributions)
-4. Identify patterns and anomalies → Generate actionable recommendations
-5. Format output per FORMAT parameter → Optionally save to docs/08-project/metrics-reports/
-
-**Example Usage**:
-```bash
-/agileflow:metrics
-/agileflow:metrics TIMEFRAME=90d EPIC=EP-0010
-/agileflow:metrics METRIC=cycle-time FORMAT=json
+Compare to previous period:
+- Show % change (↗ ↑5%, ↘ ↓12%, → stable)
+- Highlight improvements and regressions
+- Identify patterns and anomalies
+
+### 🚨 RULE #3: ALWAYS Use Health Indicators
+
+Quick status assessment:
+- 🟢 Green: Healthy/on-track (no action needed)
+- 🟡 Yellow: At-risk/monitor (may need attention)
+- 🔴 Red: Critical/off-track (action required)
+
+### 🚨 RULE #4: ALWAYS Include Actionable Recommendations
+
+Every metric should suggest:
+- What's good (continue this)
+- What needs attention (action item)
+- How to improve (specific suggestion)
+
+---
+
+## Key Metrics Calculated
+
+10+ core metrics:
+1. **Cycle Time** - in-progress → done
+2. **Lead Time** - created → done
+3. **Throughput** - stories completed/period
+4. **WIP** - current in-progress + in-review
+5. **Agent Utilization** - work distribution
+6. **Epic Health** - progress % + trend
+7. **Estimation Accuracy** - estimate vs actual
+8. **Blocked Stories** - count + duration
+9. **Flow Efficiency** - active vs total time %
+10. **Cumulative Flow Diagram** - stacked area chart
+
+---
+
+## Input Parameters
+
+```
+TIMEFRAME=7d|30d|90d|all      # Date range (default: 30d)
+EPIC=<EP_ID>                   # Filter by epic (optional)
+OWNER=<AG_*>                   # Filter by agent (optional)
+FORMAT=ascii|json|csv          # Output format (default: ascii)
+METRIC=cycle-time|lead-time|throughput|all  # Which metrics
 ```
 
-**Output**: ASCII dashboard with key metrics, WIP status, epic health, and recommendations
+**Data Sources** (read-only):
+1. docs/09-agents/bus/log.jsonl - Event timestamps
+2. docs/09-agents/status.json - Current state
+3. docs/06-stories/**/US-*.md - Story metadata
+4. docs/05-epics/*.md - Epic data
+
+---
+
+## Output Structure
+
+**Dashboard Includes**:
+- Header with timeframe & generation timestamp
+- Key Metrics section (cycle time, lead time, throughput, WIP)
+- Work In Progress status (current WIP vs limit)
+- Epic Health summary (progress bars + status)
+- Recommendations (prioritized action items)
+
+**Key Metrics Section**:
+- Current value (average/median)
+- Trend (↗↘→ with % change)
+- Previous period comparison
+- Health indicator (🟢🟡🔴)
+
+**Epic Health**:
+- Progress bar (% complete)
+- Status indicator (🟢🟡🔴)
+- ETA (weeks to completion)
+- Blockers count
+
+**Recommendations**:
+- HIGH: Immediate action (blockers, WIP violations)
+- MEDIUM: Process improvements
+- LOW: Long-term optimizations
+
+---
+
+## Anti-Patterns & Correct Usage
+
+❌ **DON'T**:
+- Assume or estimate metrics (calculate from data)
+- Skip trend comparison (context matters)
+- Use vague status (use 🟢🟡🔴)
+- Ignore actionable recommendations
+
+✅ **DO**:
+- Calculate all metrics from raw data
+- Show % change vs previous period
+- Use health indicators for quick assessment
+- Provide specific actionable next steps
+
+---
+
+## Follow-up Integration
+
+After displaying metrics:
+- `/agileflow:velocity` - See velocity trends
+- `/agileflow:blockers` - Drill into blockers
+- `/agileflow:retro` - Analyze patterns retrospectively
+- Save metrics report for stakeholder updates
+
+---
+
+## REMEMBER AFTER COMPACTION
 
-**Integration**: After `/velocity` for trends, before `/retro` for retrospective data, auto-triggered by `/babysit`
+- Command is read-only (analyzes bus/log.jsonl + status.json)
+- Calculates 10+ metrics (cycle-time, lead-time, throughput, WIP, etc.)
+- Shows trends (↗ ↘ →) with % change vs previous period
+- Uses health indicators (🟢🟡🔴) for quick assessment
+- Provides actionable recommendations (HIGH/MEDIUM/LOW)
+- Saves reports to docs/08-project/metrics-reports/
+- Always includes timeframe and generation timestamp
 
 <!-- COMPACT_SUMMARY_END -->