maestro-flow 0.3.14 → 0.3.16

package/workflows/retrospective.md

@@ -40,19 +40,18 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 ## Stage 1: parse_input
 
 ```
-1. Verify .workflow/ exists; else error E001.
-2. Tokenize $ARGUMENTS:
-   - First non-flag token: phase number, range "N..M", or "--all"
-   - Flags: --lens, --no-route, --all, --compare, --auto-yes
-3. Build:
-     mode = "scan" | "single" | "range" | "all"
-     phases = [] (filled in Stage 2)
-     lenses = ["technical","process","quality","decision"]
-     route = true (false if --no-route)
-     compare_to = null | <phase number>
-     auto_yes = false
-4. Validate --lens names. Unknown name → error E002.
-5. Validate --compare requires single mode. Else error E003.
+Require .workflow/ exists (E001).
+Parse $ARGUMENTS → first non-flag token as phase/range/"--all", remaining as flags.
+
+Build config:
+  mode       = "scan" | "single" | "range" | "all"
+  phases     = [] (filled in Stage 2)
+  lenses     = ["technical","process","quality","decision"]
+  route      = true (false if --no-route)
+  compare_to = null | <phase number>
+  auto_yes   = false
+
+Validate: --lens names must be known (E002), --compare requires single mode (E003).
 ```
 
 ---
@@ -60,28 +59,13 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 ## Stage 2: scan_unreviewed (mode = "scan" or "all")
 
 ```
-candidates = []
-
 Read .workflow/state.json → state
-artifacts = state.artifacts ?? []
-
-// Resolve completed phases from artifact registry
-phaseNums = [...new Set(artifacts.map(a => a.phase).filter(Boolean))]
-FOR each phaseNum in phaseNums:
-  execArt = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum && a.status === 'completed')
-  IF execArt:
-    artifact_dir = ".workflow/" + execArt.path
-    has_retro = file exists at "{artifact_dir}/retrospective.json"
-    candidates.push({
-      number: phaseNum,
-      slug: execArt.slug ?? "phase-" + phaseNum,
-      title: execArt.title ?? execArt.slug ?? "Phase " + phaseNum,
-      completed_at: execArt.completed_at,
-      has_retro: has_retro,
-      phase_dir: artifact_dir,
-      gaps: 0,
-      review_verdict: "—"
-    })
+
+candidates = all completed execute artifacts from state.artifacts, each mapped to:
+  { number, slug, title, completed_at, has_retro, phase_dir, gaps: 0, review_verdict: "—" }
+
+  where phase_dir = ".workflow/" + artifact.path
+        has_retro = exists "{phase_dir}/retrospective.json"
 ```
 
 ### Display backlog
@@ -111,10 +95,7 @@ FOR each phaseNum in phaseNums:
 
 If overwriting existing retrospective.json:
 ```
-mkdir -p "{candidate.phase_dir}/.history"   // phase_dir is artifact_dir from registry
-TIMESTAMP = format(now(), "YYYY-MM-DDTHH-mm-ss")
-mv "{candidate.phase_dir}/retrospective.json" "{candidate.phase_dir}/.history/retrospective-{TIMESTAMP}.json"
-mv "{candidate.phase_dir}/retrospective.md"   "{candidate.phase_dir}/.history/retrospective-{TIMESTAMP}.md"
+Archive existing retrospective.{json,md} to "{candidate.phase_dir}/.history/retrospective-{YYYY-MM-DDTHH-mm-ss}.{ext}"
 ```
 
 ---
@@ -124,65 +105,43 @@ mv "{candidate.phase_dir}/retrospective.md"   "{candidate.phase_dir}/.history/re
 For each selected phase (using `candidate.phase_dir` resolved in Stage 2), build the in-memory artifacts bundle:
 
 ```
-phase_dir = candidate.phase_dir  // already resolved from artifact registry (e.g. .workflow/scratch/plan-auth-2026-04-20)
-
-artifacts = {
-  phase_num: NN,
-  phase_slug: slug,
-  artifact_dir: artifact_dir,
-  index: read "{artifact_dir}/index.json" or null,
-  state: read .workflow/state.json,
-  plan: read "{artifact_dir}/plan.json" or null,
-  verification: read "{artifact_dir}/verification.json" or null,
-  review: read "{artifact_dir}/review.json" or null,
-  uat: read "{artifact_dir}/uat.md" or null,
-  task_summaries: read all "{artifact_dir}/.summaries/TASK-*-summary.md",
-  task_jsons: read all "{artifact_dir}/.task/TASK-*.json",
-  phase_issues: filter ".workflow/issues/issues.jsonl" + ".workflow/issues/issue-history.jsonl"
-                where issue.phase_ref == phase_slug or issue.phase_ref == NN,
-  prior_retro: null
-}
+artifact_dir = candidate.phase_dir  (resolved from artifact registry)
 
-// Resolve --compare target
-IF --compare M:
-  compareArt = state.artifacts.find(a => a.type === 'execute' && a.phase === M)
-  IF compareArt:
-    artifacts.prior_retro = read ".workflow/" + compareArt.path + "/retrospective.json"
-}
+Load artifacts bundle from artifact_dir:
+  index           ← {artifact_dir}/index.json
+  state           ← .workflow/state.json
+  plan            ← {artifact_dir}/plan.json
+  verification    ← {artifact_dir}/verification.json
+  review          ← {artifact_dir}/review.json
+  uat             ← {artifact_dir}/uat.md
+  task_summaries  ← {artifact_dir}/.summaries/TASK-*-summary.md
+  task_jsons      ← {artifact_dir}/.task/TASK-*.json
+  phase_issues    ← .workflow/issues/{issues,issue-history}.jsonl filtered by phase_ref == slug|NN
+  prior_retro     ← if --compare M: load phase M's retrospective.json via artifact registry
 ```
 
 ### Compute base metrics
 
 ```
 metrics = {
-  tasks_planned: plan?.tasks?.length or task_jsons.length,
-  tasks_completed: count task_jsons where status == "completed",
-  tasks_deferred: state.accumulated_context.deferred?.filter(d => d.phase == NN)?.length or 0,
-  gaps_found: verification?.gaps?.length or 0,
-  gaps_closed: verification?.gaps?.filter(g => g.status == "closed")?.length or 0,
-  antipatterns: verification?.antipatterns?.length or 0,
-  constraint_violations: verification?.constraint_violations?.length or 0,
-  issues_opened: phase_issues.filter(i => i.source in ["verification","review","antipattern","discovery"]).length,
-  issues_closed: phase_issues.filter(i => i.status in ["completed","failed"]).length,
-  rework_iterations: count entries in .history/ matching verification-*.json,
-  severity_distribution: review?.severity_distribution or {critical:0,high:0,medium:0,low:0,total:0},
-  review_verdict: review?.verdict or "not_run",
-  review_level: review?.level or null,
-  uat_blockers: count blockers parsed from uat.md or 0
+  tasks_planned          ← plan.tasks.length or task_jsons.length
+  tasks_completed        ← task_jsons where status=="completed"
+  tasks_deferred         ← state.accumulated_context.deferred for this phase
+  gaps_found / closed    ← verification.gaps (total vs status=="closed")
+  antipatterns           ← verification.antipatterns count
+  constraint_violations  ← verification.constraint_violations count
+  issues_opened          ← phase_issues where source in [verification,review,antipattern,discovery]
+  issues_closed          ← phase_issues where status in [completed,failed]
+  rework_iterations      ← count .history/verification-*.json
+  severity_distribution  ← review.severity_distribution or {critical:0,high:0,medium:0,low:0,total:0}
+  review_verdict/level   ← review.verdict or "not_run", review.level
+  uat_blockers           ← count blockers from uat.md
 }
 ```
 
-If `--compare M` is set, also compute delta:
+If `--compare M` is set, compute delta (current minus prior_retro) for:
 ```
-delta = {
-  vs_phase: M,
-  tasks_completed: metrics.tasks_completed - prior_retro.metrics.tasks_completed,
-  gaps_found:      metrics.gaps_found      - prior_retro.metrics.gaps_found,
-  issues_opened:   metrics.issues_opened   - prior_retro.metrics.issues_opened,
-  rework_iterations: metrics.rework_iterations - prior_retro.metrics.rework_iterations,
-  severity_critical: metrics.severity_distribution.critical - prior_retro.metrics.severity_distribution.critical,
-  severity_high:     metrics.severity_distribution.high     - prior_retro.metrics.severity_distribution.high
-}
+delta = { vs_phase, tasks_completed, gaps_found, issues_opened, rework_iterations, severity_critical, severity_high }
 ```
 
 ---
@@ -287,19 +246,11 @@ Return ONLY a single JSON object, no prose, matching this schema:
 **decision**:
 > Reconstruct the key decisions made during the phase, their stated rationale, and the alternatives rejected. Where did mid-phase pivots happen and why? What constraints surfaced late? Watch for: decisions made without recorded rationale, late pivots that suggest weak upfront framing.
 
-### Spawn pattern (single message, all lenses parallel)
+### Spawn pattern
 
-```
-For each lens in lenses:
-  Agent({
-    subagent_type: "general-purpose",
-    description: "Retrospective: {lens} lens for phase {NN}",
-    prompt: <rendered lens prompt template>,
-    run_in_background: false
-  })
-```
+Spawn all active lenses in parallel as `general-purpose` Agents (run_in_background: false), each receiving the rendered lens prompt template.
 
-Collect lens results into `lens_results = { technical: {...}, process: {...}, quality: {...}, decision: {...} }`. If any lens agent fails, log warning W001 and proceed with the lenses that returned.
+Collect results into `lens_results = { technical, process, quality, decision }`. If any lens fails, log W001 and proceed with successful lenses.
 
 ---
 
@@ -309,141 +260,23 @@ Merge lens results into the canonical retrospective record.
 
 ### Generate insight IDs
 
-For each insight across all lenses, generate `INS-{8 lowercase hex chars}` using a stable hash of `phase_num + lens + title` so re-runs do not duplicate.
+Assign `INS-{8 lowercase hex}` per insight using stable hash of `phase_num + lens + title` (idempotent across re-runs).
 
 ### Build retrospective.json
 
-```
-retrospective = {
-  phase: NN,
-  phase_slug: slug,
-  phase_title: index.title,
-  retrospected_at: now() ISO 8601 UTC,
-  lenses_run: [...lens names that returned],
-  metrics: <from Stage 3>,
-  delta: <from Stage 3 if --compare set, else null>,
-  findings_by_lens: {
-    technical: { wins, challenges, watch_patterns },
-    process:   { wins, challenges, watch_patterns },
-    quality:   { wins, challenges, watch_patterns },
-    decision:  { wins, challenges, watch_patterns }
-  },
-  distilled_insights: [
-    {
-      id: "INS-a1b2c3d4",
-      lens: "technical",
-      category: "pattern",
-      title: "...",
-      summary: "...",
-      confidence: "high",
-      evidence_refs: [...],
-      tags: [...],
-      routed_to: "spec",
-      routed_id: null   // filled in Stage 6
-    },
-    ...
-  ],
-  routing_recommendations: [
-    { insight_id: "INS-a1b2c3d4", target: "spec", rationale: "..." },
-    { insight_id: "INS-...", target: "issue", rationale: "..." },
-    { insight_id: "INS-...", target: "note",  rationale: "..." }
-  ],
-  tweetable: "Phase {NN} ({title}): {N} tasks shipped, {gaps} gaps closed, verdict {verdict}. {top_insight_title}"
-}
-```
+Assemble the canonical record with structure: `{ phase, phase_slug, phase_title, retrospected_at, lenses_run, metrics, delta, findings_by_lens, distilled_insights, routing_recommendations, tweetable }`. See full schema in [Schemas](#retrospectivejson) section. Each insight's `routed_id` is null here (populated in Stage 6).
 
 ### Build retrospective.md (human-readable)
 
-```markdown
-# Phase {NN} Retrospective: {title}
-
-> {tweetable}
-
-**Phase**: {phase_slug}
-**Retrospected**: {retrospected_at}
-**Lenses**: {lenses_run joined by ", "}
-
-## Metrics
-
-| Metric | Value |
-|--------|-------|
-| Tasks planned / completed / deferred | {planned} / {completed} / {deferred} |
-| Gaps found / closed | {gaps_found} / {gaps_closed} |
-| Issues opened / closed | {issues_opened} / {issues_closed} |
-| Antipatterns | {antipatterns} |
-| Constraint violations | {constraint_violations} |
-| Rework iterations | {rework_iterations} |
-| Review verdict | {review_verdict} ({review_level}) |
-| Severity (C/H/M/L) | {critical}/{high}/{medium}/{low} |
-| UAT blockers | {uat_blockers} |
-
-{IF delta:
-## Delta vs Phase {compare_to}
-
-| Metric | Delta |
-|--------|-------|
-| Tasks completed | {±N} |
-| Gaps found | {±N} |
-| Issues opened | {±N} |
-| Rework iterations | {±N} |
-| Critical findings | {±N} |
-| High findings | {±N} |
-}
-
-## Findings by Lens
-
-{FOR each lens in [technical, process, quality, decision]:}
-### {Lens title}
-
-**Wins**
-1. {win.title} — {evidence_refs joined by ", "}
-2. ...
-3. ...
-
-**Challenges**
-1. {challenge.title} — {evidence_refs}
-2. ...
-3. ...
-
-**Watch patterns**
-1. {watch.title} — {evidence_refs}
-2. ...
-3. ...
-
-{END FOR}
-
-## Distilled Insights
-
-{FOR each insight in distilled_insights:}
-### {INS-id}: {title}
-
-- **Category**: {category}
-- **Lens**: {lens}
-- **Confidence**: {confidence}
-- **Tags**: {tags}
-- **Routed to**: {routed_to} ({routed_id or "pending"})
-
-{summary}
+Render a markdown report with these sections:
+1. **Header**: tweetable quote, phase metadata, lenses run
+2. **Metrics table**: all metrics fields from Stage 3
+3. **Delta table** (if --compare): ± values for key metrics
+4. **Findings by Lens**: for each lens → numbered wins, challenges, watch_patterns with evidence_refs
+5. **Distilled Insights**: per insight → category, lens, confidence, tags, routed_to, summary, evidence refs
+6. **Routing Recommendations table**: insight_id | target | rationale
 
-**Evidence**:
-{FOR ref in evidence_refs:} - `{ref}`{END FOR}
-
-{END FOR}
-
-## Routing Recommendations
-
-| Insight | Target | Rationale |
-|---------|--------|-----------|
-| {INS-id} | spec | ... |
-| {INS-id} | issue | ... |
-| {INS-id} | note | ... |
-```
-
-Write both files (phase_dir already resolved in Stage 2):
-```
-Write "{artifact_dir}/retrospective.json"
-Write "{artifact_dir}/retrospective.md"
-```
+Write both `{artifact_dir}/retrospective.json` and `{artifact_dir}/retrospective.md`.
 
 ---
 
@@ -477,34 +310,18 @@ Route spec-routed insights as `<spec-entry>` entries into the appropriate catego
 - quality-related → `quality`
 
 ```
-category = map_insight_to_category(insight.type)
-target_file = category_to_file(category)  # e.g., coding → coding-conventions.md
-
-keywords = extract_keywords(insight.title + insight.summary)  # 3-5 domain-specific terms
-
-Append to .workflow/specs/{target_file}:
-  <spec-entry category="{category}" keywords="{keywords}" date="{YYYY-MM-DD}" source="retrospective">
+Map insight type → category → target file:
+  pattern/convention → coding → coding-conventions.md
+  adr-candidate/architecture → arch → arch-decisions.md
+  quality-related → quality → quality-conventions.md
 
-  ### {insight.title}
+Append <spec-entry> to .workflow/specs/{target_file} with:
+  category, keywords (3-5 extracted from title+summary), date, source="retrospective"
+  Body: insight title, summary, evidence refs, phase/lens/INS_id/confidence metadata
 
-  {insight.summary}
+Create target file with category frontmatter if it does not exist.
 
-  **Evidence:** {FOR ref in evidence_refs:} `{ref}` {END FOR}
-  **Phase:** {NN} ({phase_slug}) | **Lens:** {lens} | **Insight:** {INS_id} | **Confidence:** {insight.confidence}
-
-  </spec-entry>
-```
-
-If the target file does not exist, create it with category frontmatter first (same as `spec-add` on-demand creation).
-
-## Routing trail
-
-- Phase: {NN}-{phase_slug}
-- Lens: {lens}
-- Insight: {INS_id}
-- Confidence: {confidence}
-
-insight.routed_id = "{category_file}#INS-{INS_id}"  # e.g., coding-conventions.md#INS-a1b2c3d4
+insight.routed_id = "{category_file}#INS-{INS_id}"
 ```
 
 #### Target: note
@@ -512,88 +329,37 @@ insight.routed_id = "{category_file}#INS-{INS_id}"  # e.g., coding-conventions.m
 Reuse the existing `manage-learn` skill in tip mode — do not duplicate the learning pipeline.
 
 ```
-note_text = "[Retro phase {NN} / {lens}] {insight.title}: {insight.summary}"
-tags = insight.tags + ["retrospective", "phase-{NN}", insight.lens]
-
-Skill({
-  skill: "manage-learn",
-  args: "tip \"{note_text}\" --tag " + tags.join(",")
-})
+Invoke manage-learn tip with:
+  text = "[Retro phase {NN} / {lens}] {insight.title}: {insight.summary}"
+  tags = insight.tags + ["retrospective", "phase-{NN}", insight.lens]
 
-Capture the returned TIP-{id} from the skill output.
 insight.routed_id = "TIP-{captured_id}"
 ```
 
-If the skill call cannot be intercepted to capture the ID, fall back to writing the tip file directly using the schema in `workflows/memory.md` Part B Step 3 (Tip mode), and update `wiki-index.json` per Step 4.
+Fallback: if skill ID cannot be captured, write tip file directly per `workflows/knowhow.md` Part B Step 3 and update `wiki-index.json` per Step 4.
 
 #### Target: issue
 
 Append a new entry to `.workflow/issues/issues.jsonl` matching the canonical schema from `workflows/issue.md` Step 4.
 
 ```
-mkdir -p ".workflow/issues"
-touch ".workflow/issues/issues.jsonl"
-
-# Generate next ID for today (scan both active and history)
-today = format(now(), "YYYYMMDD")
-existing_ids = []
-read .workflow/issues/issues.jsonl       → collect ids matching ISS-{today}-*
-read .workflow/issues/issue-history.jsonl → collect ids matching ISS-{today}-*
-counter = max sequence number from existing_ids + 1, or 1 if none
-issue_id = "ISS-{today}-{counter padded to 3 digits}"
-
-# Map insight category → severity (operator on the insight, not finding severity)
-severity = match insight.category:
-  "antipattern" → "high"
-  "gotcha"      → "medium"
-  "pattern"     → "low"
-  "decision"    → "low"
-  "tool"        → "low"
-  "technique"   → "low"
-  default       → "medium"
-
-priority = match severity:
-  critical → 1
-  high     → 2
-  medium   → 3
-  low      → 4
-
-issue = {
-  id: issue_id,
-  title: "[Retro] {insight.title}" (truncated to 100 chars),
-  status: "open",
-  priority: priority,
-  severity: severity,
-  source: "retrospective",
-  phase_ref: phase_slug,
-  gap_ref: insight.id,
-  description: insight.summary,
-  fix_direction: "Surfaced by phase {NN} retrospective ({lens} lens). " +
-                 "Review evidence refs and determine fix scope.",
-  context: {
-    location: insight.evidence_refs[0] or "",
-    suggested_fix: "",
-    notes: "Confidence: " + insight.confidence
-  },
-  tags: insight.tags + ["retrospective", "phase-" + NN, insight.lens],
-  affected_components: [],
-  feedback: [],
-  issue_history: [
-    {
-      timestamp: now ISO,
-      from_status: null,
-      to_status: "open",
-      actor: "retrospective",
-      note: "Auto-created from phase " + NN + " retrospective insight " + insight.id
-    }
-  ],
-  created_at: now ISO,
-  updated_at: now ISO,
-  resolved_at: null,
-  resolution: null
-}
+Ensure .workflow/issues/issues.jsonl exists.
+
+Generate issue_id = "ISS-{YYYYMMDD}-{NNN}" (next sequence from issues.jsonl + issue-history.jsonl).
+
+Map insight.category → severity:
+  antipattern→high, gotcha→medium, pattern/decision/tool/technique→low, default→medium
+Map severity → priority: critical→1, high→2, medium→3, low→4
+
+Create issue per canonical schema (workflows/issue.md Step 4):
+  title: "[Retro] {insight.title}" (max 100 chars)
+  source: "retrospective", phase_ref: phase_slug, gap_ref: insight.id
+  description: insight.summary
+  fix_direction: "Surfaced by phase {NN} retrospective ({lens} lens). Review evidence refs."
+  tags: insight.tags + ["retrospective", "phase-{NN}", insight.lens]
+  Initial issue_history entry with actor="retrospective"
 
-Append serialized JSON line to .workflow/issues/issues.jsonl
+Append to .workflow/issues/issues.jsonl
 insight.routed_id = issue_id
 ```
 
@@ -610,84 +376,32 @@ Append every distilled insight (regardless of routing target, including `routed_
 ### Bootstrap
 
 ```
-mkdir -p ".workflow/learning"
-touch ".workflow/learning/lessons.jsonl"
-
-INDEX_FILE = ".workflow/learning/learning-index.json"
-IF NOT exists INDEX_FILE:
-  Write '{"entries":[],"_metadata":{"created":"' + now ISO + '","version":"1.0"}}'
+Ensure .workflow/learning/lessons.jsonl and learning-index.json exist.
+Initialize learning-index.json with {"entries":[],"_metadata":{"created":"...","version":"1.0"}} if new.
 ```
 
 ### Append rows
 
-For each insight in `distilled_insights`:
-
-```
-row = {
-  id: insight.id,
-  phase: NN,
-  phase_slug: phase_slug,
-  lens: insight.lens,
-  category: insight.category,
-  title: insight.title,
-  summary: insight.summary,
-  confidence: insight.confidence,
-  tags: insight.tags,
-  evidence_refs: insight.evidence_refs,
-  routed_to: insight.routed_to,
-  routed_id: insight.routed_id,
-  source: "retrospective",
-  captured_at: now ISO
-}
-
-Append serialized JSON line to .workflow/learning/lessons.jsonl
-```
+For each insight in `distilled_insights`, append a JSON line to `.workflow/learning/lessons.jsonl` with fields:
+`{ id, phase, phase_slug, lens, category, title, summary, confidence, tags, evidence_refs, routed_to, routed_id, source: "retrospective", captured_at }`
 
 ### Update index
 
-```
-Read .workflow/learning/learning-index.json
-For each new insight:
-  Append to entries[]:
-    {
-      id: insight.id,
-      type: "insight",
-      timestamp: now ISO,
-      file: "lessons.jsonl",
-      summary: insight.title (truncated to 80 chars),
-      tags: insight.tags,
-      lens: insight.lens,
-      category: insight.category,
-      phase: NN,
-      phase_slug: phase_slug,
-      confidence: insight.confidence,
-      routed_to: insight.routed_to,
-      routed_id: insight.routed_id
-    }
-Write .workflow/learning/learning-index.json
-```
+Append an entry to `.workflow/learning/learning-index.json` entries[] for each new insight:
+`{ id, type: "insight", timestamp, file: "lessons.jsonl", summary (80 chars), tags, lens, category, phase, phase_slug, confidence, routed_to, routed_id }`
 
 ### Backward-compat append to specs/learnings.md
 
 Append learnings to `.workflow/specs/learnings.md` (shared with milestone-complete's learning extraction) using `<spec-entry>` closed-tag format:
 
 ```
-IF .workflow/specs/learnings.md exists:
-  FOR each insight:
-    keywords = extract_keywords(insight.title + insight.summary)  # 3-5 domain-specific terms
-    Append:
-      <spec-entry category="learning" keywords="{keywords}" date="{YYYY-MM-DD}" source="retrospective">
-
-      ### {title}
+Append each insight to .workflow/specs/learnings.md as <spec-entry> with:
+  category="learning", keywords (3-5 extracted), date, source="retrospective"
+  Body: title, summary, phase/lens/INS_id metadata
 
-      {summary}
-      Phase: {NN} | Lens: {lens} | Insight: {INS_id}
-
-      </spec-entry>
+Create file with category frontmatter + "## Entries" header if it does not exist.
 ```
 
-If the file does not exist, create it with category frontmatter and a `## Entries` header.
-
 ---
 
 ## Stage 8: next_step
@@ -695,38 +409,16 @@ If the file does not exist, create it with category frontmatter and a `## Entrie
 Print confirmation banner and route the user.
 
 ```
-=== RETROSPECTIVE COMPLETE ===
-Phase:           {NN} ({phase_slug})
-Lenses run:      {lenses joined by ", "}
-Insights:        {count}
-
-Routing summary:
-  Spec entries:    {N}  → .workflow/specs/{category-file}.md
-  Notes saved:     {N}  → .workflow/memory/TIP-*
-  Issues opened:   {N}  → .workflow/issues/issues.jsonl
-  Lessons logged:  {N}  → .workflow/learning/lessons.jsonl
-
-Files:
-  {artifact_dir}/retrospective.md
-  {artifact_dir}/retrospective.json
+Print banner: phase, lenses run, insight count, routing summary (spec/note/issue/lesson counts with target paths), output file paths.
 
-Next steps (suggested):
-  Skill({ skill: "manage-status" })                                    — Review project state
-  Skill({ skill: "manage-issue", args: "list --source retrospective" }) — Triage created issues
-  Skill({ skill: "manage-learn", args: "list" })                       — Browse the lessons library
-  Skill({ skill: "maestro-milestone-audit" })                          — Audit milestone if all phases done
+Suggested next steps:
+  manage-status                              — Review project state
+  manage-issue list --source retrospective   — Triage created issues
+  manage-learn list                          — Browse the lessons library
+  maestro-milestone-audit                    — Audit milestone if all phases done
 ```
 
-If `mode == "range"` or `--all`, loop Stages 3–8 per phase, then print an aggregate summary at the end:
-
-```
-=== RETROSPECTIVE BATCH COMPLETE ===
-Phases retrospected: {count}
-Total insights:      {sum}
-Total specs:         {sum}
-Total notes:         {sum}
-Total issues:        {sum}
-```
+If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate batch summary (phases retrospected, total insights/specs/notes/issues).
 
 ---
 
@@ -828,34 +520,3 @@ One JSON object per line:
 }
 ```
 
----
-
-## Error Codes
-
-| Code | Severity | Description |
-|------|----------|-------------|
-| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first |
-| E002 | error | Unknown `--lens` name (must be one of: technical, process, quality, decision) |
-| E003 | error | `--compare` requires a single phase argument |
-| E004 | error | Phase argument resolves to a phase that has not executed yet (no `.task/` or `.summaries/`) |
-| E005 | error | Phase argument out of range / phase directory not found |
-| W001 | warning | One or more lens agents failed — proceeding with partial lens coverage |
-| W002 | warning | Existing retrospective.json found and not `--all`/`--force` — prompted user to overwrite |
-| W003 | warning | `manage-memory-capture` skill returned without parseable TIP id; fell back to direct write |
-| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted |
-
----
-
-## Success Criteria
-
-- [ ] `.workflow/` exists and target phase resolved
-- [ ] All requested lenses returned valid JSON (or partial-coverage warning W001 logged)
-- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights
-- [ ] `retrospective.md` written and human-readable
-- [ ] Each insight has stable `INS-{8hex}` id
-- [ ] Routing executed (unless `--no-route`): every recommendation either created an artifact or was explicitly skipped by user
-- [ ] `lessons.jsonl` appended with one row per insight
-- [ ] `learning-index.json` updated
-- [ ] Issue rows match the canonical issues.jsonl schema (verifiable with `jq`)
-- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json, etc. untouched)
-- [ ] Confirmation banner printed with routing counts and next-step suggestions