maestro-flow 0.3.10 → 0.3.12

package/.claude/commands/spec-add.md

@@ -1,56 +1,67 @@
----
-name: spec-add
-description: Add a spec entry (bug, pattern, decision, or rule) to the appropriate specs file
-argument-hint: "<type> <content>"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Add a knowledge entry to the project specs system, routing it to the correct file by category.
-Each entry is timestamped and appended to learnings.md, then the relevant spec file is updated if the entry warrants a convention or rule change.
-Supports four categories: bug fixes, patterns, architectural decisions, and quality rules.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-add.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- expects `<type> <content>` where type is one of: bug, pattern, decision, rule, debug, test, review, validation
-
-**Type-to-file mapping:**
-| Type | Primary file | Secondary update |
-|------|-------------|-----------------|
-| `bug` | `learnings.md` | -- |
-| `pattern` | `learnings.md` | `coding-conventions.md` |
-| `decision` | `learnings.md` | `architecture-constraints.md` |
-| `rule` | `learnings.md` | `quality-rules.md` |
-| `debug` | `learnings.md` | `debug-notes.md` |
-| `test` | `learnings.md` | `test-conventions.md` |
-| `review` | `learnings.md` | `review-standards.md` |
-| `validation` | `learnings.md` | `validation-rules.md` |
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-add.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | Category and content are both required -- usage: `<type> <content>` | parse_input |
-| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate_entry |
-| E003 | fatal | Invalid category -- must be one of: bug, pattern, decision, rule, debug, test, review, validation | parse_input |
-</error_codes>
-
-<success_criteria>
-- [ ] Category parsed and validated as bug/pattern/decision/rule
-- [ ] Entry appended to `.workflow/specs/learnings.md` with timestamp
-- [ ] Relevant spec file updated (if type is pattern/decision/rule)
-- [ ] Confirmation report displayed
-- [ ] Next step: `/spec-load --category {type}` to verify, or continue current task
-</success_criteria>
+---
+name: spec-add
+description: Add a spec entry to the appropriate specs file by category
+argument-hint: "<category> <content>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Add a knowledge entry to the project specs system using `<spec-entry>` closed-tag format.
+Each category maps 1:1 to a single target file — no dual-write.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-add.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<category> <content>`
+
+**Category-to-file mapping (1:1, same as spec-load):**
+| Category | Target file |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+
+**Entry format (closed-tag):**
+```markdown
+<spec-entry category="{category}" keywords="{auto-extracted}" date="{YYYY-MM-DD}">
+
+### {title}
+
+{content}
+
+</spec-entry>
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-add.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Category and content are both required -- usage: `<category> <content>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate_entry |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Category parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 relevant terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format
+- [ ] Entry appended to target file
+- [ ] Confirmation report displayed
+- [ ] Next step: `/spec-load --keyword {keyword}` to verify
+</success_criteria>
+</output>

package/.claude/commands/spec-load.md

@@ -1,64 +1,66 @@
----
-name: spec-load
-description: Load relevant specs and lessons for current context (used by agents before execution)
-argument-hint: "[--category <type>] [--with-lessons] [keyword]"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-<purpose>
-Load and display relevant spec files for the current working context, optionally filtered by category.
-Designed for agents to call before execution to internalize project conventions, constraints, and learnings.
-Returns matched sections with file references ranked by relevance.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/specs-load.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional `--category <type>` flag and/or keyword to filter specs
-
-**Category filter** (matches frontmatter `category` field):
-| Category | Files loaded |
-|----------|-------------|
-| `general` | `learnings.md` |
-| `exploration` | _(reserved)_ |
-| `planning` | `architecture-constraints.md` |
-| `execution` | `coding-conventions.md`, `quality-rules.md` |
-| `debug` | `debug-notes.md` |
-| `test` | `test-conventions.md` |
-| `review` | `review-standards.md` |
-| `validation` | `validation-rules.md` |
-| `all` (default) | All spec files |
-
-**Keyword:** If provided, search within loaded files for matching sections.
-If no arguments, loads all specs for the active phase/task context.
-
-**Flags:**
-- `--with-lessons` — Also search `.workflow/learning/lessons.jsonl` for entries with `category: "gotcha"`, `"antipattern"`, or `"pattern"` relevant to the keyword or current context. Appends matched lessons after spec output. This bridges the gap between specs (prescriptive rules) and lessons (discovered knowledge).
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/specs-load.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | detect_context |
-| W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
-</error_codes>
-
-<success_criteria>
-- [ ] Category filter parsed correctly (or defaults to all)
-- [ ] Spec files resolved and read
-- [ ] Keyword filtering applied if provided
-- [ ] If `--with-lessons`: lessons.jsonl searched for gotcha/antipattern/pattern entries matching context
-- [ ] If `--with-lessons`: matched lessons displayed after specs (max 10, newest first)
-- [ ] Results displayed with file:line references
-- [ ] Relevant specs loaded into agent context
-- [ ] Next step: proceed with current task using loaded specs as context
-</success_criteria>
+---
+name: spec-load
+description: Load relevant specs and lessons for current context (used by agents before execution)
+argument-hint: "[--category <type>] [--keyword <word>] [--with-lessons]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+<purpose>
+Load and display relevant spec files for the current working context.
+Supports filtering by category (file-level) and keyword (entry-level via `<spec-entry>` tags).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-load.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags and keyword
+
+**Category-to-file mapping (1:1, same as spec-add):**
+| Category | File loaded |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+| `all` (default) | All spec files |
+
+**Flags:**
+- `--category <type>` — Filter by file category (loads one file)
+- `--keyword <word>` — Filter entries by keyword attribute in `<spec-entry>` tags. Searches across all files (or within category if combined)
+- `--with-lessons` — Also search `.workflow/learning/lessons.jsonl`
+
+**Examples:**
+```
+/spec-load --keyword auth
+/spec-load --category coding --keyword naming
+/spec-load --category arch
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-load.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | detect_context |
+| W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
+</error_codes>
+
+<success_criteria>
+- [ ] Category and/or keyword parsed from arguments
+- [ ] Spec files loaded per category mapping
+- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords attribute)
+- [ ] Legacy entries filtered by text grep fallback
+- [ ] Results displayed with file:category references
+</success_criteria>
+</output>

package/.claude/commands/spec-setup.md

@@ -11,7 +11,7 @@ allowed-tools:
 ---
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Produces four spec files plus a tech profile JSON that downstream agents and commands consume for consistent coding.
+Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
 All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
 </purpose>
 
@@ -45,13 +45,9 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 
 <success_criteria>
 - [ ] `.workflow/specs/` directory created
-- [ ] `coding-conventions.md` written with detected patterns
-- [ ] `architecture-constraints.md` written with structural rules
-- [ ] `quality-rules.md` written with auto-detected and manual sections
-- [ ] `learnings.md` initialized with format instructions
+- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
 - [ ] `project-tech.json` written with detected tech stack
-- [ ] Report displayed with summary and next steps:
-  - Build codebase docs → `/manage-codebase-rebuild`
-  - Load specs for task → `/spec-load`
-  - Add new knowledge → `/spec-add <type> <content>`
+- [ ] Report displayed with summary and next steps
 </success_criteria>
+</output>

package/.codex/skills/learn-decompose/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: learn-decompose
+description: 4-dimension parallel pattern extraction via CSV wave pipeline. Structural, behavioral, data, and error dimension agents scan in parallel (Wave 1), cross-reference agent deduplicates and catalogs (Wave 2). Outputs pattern catalog to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
+scan a module, then a cross-reference agent deduplicates against existing patterns and
+produces a catalog. Discovered patterns persist to `lessons.jsonl` and optionally to
+specs (via `spec-add`) and wiki.
+
+```
+Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
+```
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution:**
+- File path → analyze that file
+- Directory path → all source files in it
+- Module name → Glob `src/**/{module}*`
+
+**Flags:**
+- `-y, --yes`: Skip confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+- `--patterns <list>`: Comma-separated pattern names to focus on
+- `--save-spec`: Invoke `spec-add` for each new pattern
+- `--save-wiki`: Create wiki note entries per dimension group
+
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/learning/decompose-{slug}-{date}.md`
+</context>
+
+<invariants>
+1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
+2. **Evidence required**: Every finding must have file:line anchors
+3. **Dedup before persist**: Cross-reference against existing specs + lessons
+4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
+5. **No files modified outside** `.workflow/learning/` (and optionally specs/wiki)
+</invariants>
+
+<execution>
+
+### Phase 1: Session Init + Target Resolution
+
+```javascript
+const AUTO_YES = $ARGUMENTS.includes('-y') || $ARGUMENTS.includes('--yes')
+const patternsMatch = $ARGUMENTS.match(/--patterns\s+(\S+)/)
+const patternFilter = patternsMatch ? patternsMatch[1].split(',') : null
+const SAVE_SPEC = $ARGUMENTS.includes('--save-spec')
+const SAVE_WIKI = $ARGUMENTS.includes('--save-wiki')
+const target = $ARGUMENTS.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--patterns\s+\S+|--save-spec|--save-wiki/g, '').trim()
+```
+
+Resolve target to file list. Load existing patterns from `coding-conventions.md` + `lessons.jsonl` for dedup set.
+
+### Phase 2: Wave 1 — Parallel Dimension Scans
+
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
+
+| id | dimension | focus |
+|----|-----------|-------|
+| 1 | structural | Class hierarchy, composition, DI, factories, exports |
+| 2 | behavioral | Events, middleware, observer, command, state machines |
+| 3 | data | Repository, DTO, caching, serialization, validation |
+| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
+| 5 | cross-ref | Dedup + catalog from wave 1 findings |
+
+Each dimension agent returns:
+```json
+[{
+  "name": "pattern name",
+  "dimension": "structural|behavioral|data|error",
+  "confidence": "high|medium|low",
+  "anchors": ["file:line"],
+  "description": "what it does",
+  "rationale": "why this approach",
+  "tradeoffs": "what was given up"
+}]
+```
+
+### Phase 3: Wave 2 — Cross-Reference + Catalog
+
+Single agent receives all wave 1 findings via `prev_context`. Tasks:
+- Match against dedup set → mark as `documented`, `known`, or `new`
+- Merge duplicates across dimensions (same pattern found by multiple agents)
+- Flag contradictions with documented conventions
+- Build pattern catalog grouped by dimension
+
+### Phase 4: Persist
+
+1. Write `decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `lessons.jsonl` (source: "decompose", category: "pattern")
+3. If `--save-spec`: invoke `spec-add` per new pattern
+4. If `--save-wiki`: create wiki note per dimension group
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target path not found | Check path or use module name |
+| E002 | error | No source files in target | Check target has .ts/.js files |
+| W001 | warning | Dimension agent failed — partial results | Proceed with available dimensions |
+| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete file list
+- [ ] 4 dimension agents spawned in parallel via spawn_agents_on_csv
+- [ ] Each finding has: name, dimension, confidence, anchors, description
+- [ ] Cross-reference performed (documented / known / new)
+- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
+- [ ] If --save-spec / --save-wiki: entries created
+</success_criteria>

package/.codex/skills/learn-follow/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: learn-follow
+description: Guided follow-along reading of code or wiki entries. Section-by-section walk-through with 4 forcing questions, pattern extraction, and understanding map generation. Persists insights to lessons.jsonl.
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Walks through content
+section by section using 4 forcing questions to extract patterns, identify assumptions,
+and build a structured understanding map. Insights persist to `lessons.jsonl`.
+
+Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
+deep reading that builds understanding incrementally.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → Read source file
+- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
+- Topic string → Search via `maestro wiki search`, use top result
+
+**Flags:**
+- `--depth shallow` — Key patterns and structure only (default)
+- `--depth deep` — Every function, branch, assumption
+- `--save-wiki` — Create wiki note with reading notes
+
+**Output**: `.workflow/learning/follow-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target + Load Context Web
+- File: verify exists, parse imports for dependency files
+- Wiki ID: fetch + load forward/backlinks
+- Topic: search wiki, take top result
+- Build 1-hop context neighborhood (imports/exports or wiki links)
+
+### Stage 2: Build Reading Order
+- Single file: split into logical sections (function/class boundaries)
+- Directory: entry point → core modules → utilities → tests
+- `--depth shallow`: top-level structure only
+- `--depth deep`: every function body, every branch
+
+### Stage 3: Guided Reading (4 Forcing Questions per Section)
+1. **"What pattern is being used here?"** — design patterns, idioms, conventions
+2. **"Why this approach instead of alternatives?"** — trade-offs made
+3. **"What assumption does this depend on?"** — external state, input shape, ordering
+4. **"What would break if this changed?"** — fragility, downstream effects
+
+### Stage 4: Extract Patterns + Produce Understanding Map
+From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+
+Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
+
+### Stage 5: Persist
+1. Write `follow-{slug}-{date}.md` with understanding map
+2. Append new patterns to `lessons.jsonl` (source: "follow", stable INS-ids)
+3. If `--save-wiki`: create wiki note entry
+
+**Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
+| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
+| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
+| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content
+- [ ] Context web loaded (imports/exports or wiki links)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Understanding map produced with concepts, patterns, assumptions, questions
+- [ ] `follow-{slug}-{date}.md` written
+- [ ] `lessons.jsonl` appended with stable INS-ids
+</success_criteria>

package/.codex/skills/learn-investigate/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: learn-investigate
+description: Systematic question investigation with hypothesis testing, evidence logging, and 3-strike escalation. 4-phase pipeline — evidence collection, pattern matching, hypothesis testing, synthesis. Persists findings to lessons.jsonl.
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic investigation for understanding questions (not bug-fixing). 4-phase approach
+with scope lock and 3-strike escalation. Produces structured evidence trails and
+understanding documents that persist to the learning system.
+
+Unlike `quality-debug` (fixing bugs during execution), this answers "how does X work?",
+"why does Y happen?", "what would happen if Z?" questions.
+</purpose>
+
+<context>
+$ARGUMENTS — question text and optional flags.
+
+**Flags:**
+- `--scope <path>` — Restrict to files under this directory (default: entire project)
+- `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
+
+**Output**: `.workflow/learning/investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
+</context>
+
+<execution>
+
+### Stage 1: Frame the Question
+- Parse question, generate slug, create investigation directory
+- Search prior knowledge: wiki search, grep lessons.jsonl, read debug-notes.md
+- Write initial `understanding.md`
+
+### Stage 2: Evidence Collection
+1. **Code search**: Grep keywords across scoped files
+2. **File inspection**: Read most relevant files
+3. **Import tracing**: Follow dependency chain
+4. **Git history**: `git log --oneline -10 -- <relevant-files>`
+
+Each evidence item → `evidence.ndjson`:
+```json
+{"ts":"ISO","type":"code|git|search|doc","source":"file:line","relevance":"high|medium|low","content":"...","note":"..."}
+```
+
+### Stage 3: Hypothesis Formation + Testing
+Generate ranked hypotheses from evidence. For each (in rank order):
+1. Design test: what evidence would confirm/disprove?
+2. Execute test: code trace, targeted search, experiment
+3. Record result in `evidence.ndjson` (type: "test")
+4. Update `understanding.md`: confirmed / disproved / inconclusive
+
+### Stage 4: 3-Strike Escalation
+If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
+
+### Stage 5: Synthesize + Persist
+1. Write `report.md` with answer, evidence trail, hypothesis results
+2. Append to `lessons.jsonl`:
+   - Confirmed → category: "technique" / "pattern"
+   - Disproved → category: "gotcha"
+3. Display summary with next-step routing
+
+**Next steps:** `/spec-add debug <finding>`, `/learn-follow <path>`, `/learn-decompose <module>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No question provided | Provide question as first argument |
+| E002 | error | Scope path does not exist | Check --scope path |
+| W001 | warning | No prior knowledge found | Proceed with fresh investigation |
+| W002 | warning | Very few evidence matches (<3) | Broaden search terms |
+| W003 | warning | All hypotheses inconclusive | Marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Question parsed and investigation directory created
+- [ ] Evidence collected and logged to evidence.ndjson
+- [ ] At least 1 hypothesis formed and tested
+- [ ] understanding.md tracks evolving understanding
+- [ ] report.md written with answer and evidence trail
+- [ ] Findings appended to lessons.jsonl with stable INS-ids
+- [ ] 3-strike escalation triggered if all hypotheses fail
+</success_criteria>

package/.codex/skills/learn-retro/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: learn-retro
+description: Unified retrospective via CSV wave pipeline. Git lens (commit metrics, session detection, hotspots) and decision lens (multi-perspective evaluation via 3 parallel agents) with lens-based selection. Persists insights to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation.
+Two lenses, usable independently or together:
+- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trends
+- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation via 3 parallel agents
+
+Works on raw git history and wiki/spec data — does not require completed phase artifacts.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens:** `--lens git` | `--lens decision` | `--lens all` (default)
+
+**Git flags:** `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare`
+**Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
+
+**Output**: `.workflow/learning/retro-{date}.md` + `retro-{date}.json`
+</context>
+
+<execution>
+
+### Phase 1: Parse + Select Lenses
+
+### Phase 2: Git Lens (skip if --lens decision)
+**Sequential data gathering** (parallel git commands):
+- Commit stats with shortstat
+- Per-commit numstat for test/production LOC split
+- Timestamps for session detection (>2hr gap clustering)
+- File hotspots (most frequently changed)
+- Per-author commit counts
+
+**Compute**: commits, LOC, test ratio, churn rate, active days, sessions, per-author breakdown.
+**Trend comparison** if prior `retro-*.json` exists.
+
+### Phase 3: Decision Lens (skip if --lens git)
+**3a: Collect decisions** from wiki, specs, git log, phase context, lessons.jsonl.
+**3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
+
+**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
+
+| id | perspective | focus |
+|----|------------|-------|
+| 1 | technical | Implementation vs intent, context drift. Grade: sound/degraded/violated |
+| 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
+| 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
+
+**3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
+
+### Phase 4: Unified Report
+Write `retro-{date}.md` + `retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
+
+### Phase 5: Persist
+Append insights to `lessons.jsonl` (source: "retro-git" or "retro-decision"). Display summary.
+
+**Next steps:** `/learn-follow <path>`, `/quality-test-gen <area>`, `/learn-investigate <question>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Not inside git repo (git lens) | Navigate to git repo |
+| E002 | error | No commits in time window | Increase --days |
+| E003 | error | No decisions found (decision lens) | Check wiki/specs content |
+| W001 | warning | .workflow/learning/ not found | Auto-bootstrap |
+| W002 | warning | No prior retro for comparison | First retro establishes baseline |
+| W003 | warning | Decision perspective agent failed | Proceed with partial evaluation |
+</error_codes>
+
+<success_criteria>
+- [ ] Lens selection parsed correctly
+- [ ] Git lens: metrics computed, sessions detected, hotspots identified
+- [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
+- [ ] Unified report written to retro-{date}.md + retro-{date}.json
+- [ ] lessons.jsonl appended with insights (stable INS-ids)
+</success_criteria>