quality-retrospective

<purpose>
Post-execution retrospective (复盘): four parallel lenses (technical/process/quality/decision) → distill insights → route to spec/knowhow/issue stores.
</purpose>

<required_reading>
@~/.maestro/workflows/retrospective.md
</required_reading>

<deferred_reading>
- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
</deferred_reading>

<context>
Arguments: $ARGUMENTS

Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
</context>

<execution>
Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.

### Phase Gates (MANDATORY, BLOCKING)

**GATE 1: Input → Lens Analysis** (Stages 1-3 → Stage 4)
- REQUIRED: Mode resolved (scan/single/range/all) and phases validated.
- REQUIRED: At least one phase selected with status=completed and existing artifacts.
- REQUIRED: Read-only — no file writes in Stages 1-3.
- BLOCKED if no valid phases: E004/E005.

**GATE 2: Lens Analysis → Routing** (Stages 4-5 → Stage 6)
- REQUIRED: All requested lens agents returned valid JSON (or W001 logged for partial).
- REQUIRED: Insights distilled with stable `INS-{8hex}` IDs.
- REQUIRED: Archive existing `retrospective.{md,json}` before overwrite.
- BLOCKED if all lens agents failed: cannot synthesize without results.

**GATE 3: Routing → Completion** (Stage 6 → Stages 7-8)
- REQUIRED: `retrospective.json` written with metrics, findings, insights, routing.
- REQUIRED: `retrospective.md` written (human-readable).
- REQUIRED: Issue rows match canonical `issues.jsonl` schema (status "open", full fields).
- REQUIRED: Note tips routed via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`.
- BLOCKED if routing incomplete: finish all write operations before reporting.

### Execution Constraints

- **Parallel lens dispatch**: Stage 4 spawns one Agent per active lens in a single message.
- **Stable IDs**: `INS-{8 hex}` from `hash(phase_num + lens + title)` — re-runs do not duplicate.
- **No source modification**: Never modify verification.json, review.json, plan.json.
- **Backward-compat**: Append to `.workflow/specs/learnings.md` only if file already exists.
</execution>

<error_codes>
| Code | Severity | Description | Stage |
|------|----------|-------------|-------|
| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
| E003 | error | `--compare` requires a single phase argument | parse_input |
| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS id; fell back to direct write | route_outputs |
| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
</error_codes>

<success_criteria>
- [ ] Mode correctly resolved (scan / single / range / all)
- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
- [ ] Each insight has a stable `INS-{8hex}` id
- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
- [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
- [ ] Note tips (if any) created via `Skill({ skill: "manage-knowhow-capture", args: "tip ..." })`
- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
- [ ] Confirmation banner displays routing counts and next-step suggestions
</success_criteria>

<completion>
### Standalone report

```
--- COMPLETION STATUS ---
STATUS: DONE|DONE_WITH_CONCERNS
CONCERNS: {description if applicable}
--- END STATUS ---
```

### Ralph-invoked completion

End the step by calling the CLI (no text block output):
```
maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
```

### Next-step routing

| Condition | Suggestion |
|-----------|-----------|
| Insights routed | `/manage-status` |
| Issues created | `/manage-issue list --source retrospective` |
| Knowhow captured | `/manage-knowhow list` |
| More phases to review | `/quality-retrospective --all` |
</completion>