session-orchestrator 3.16.0

package/skills/plan/mode-new.md

@@ -0,0 +1,297 @@
+# Mode: `/plan new` — Project Kickoff
+
+> Reference file for the plan skill. Read by SKILL.md when mode is `new`.
+> Covers: requirement gathering (3 waves) → PRD generation → repo setup → issue creation.
+> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). New repos pick the file appropriate to the platform that will operate them.
+
+---
+
+## Phase 1: Requirement Gathering (3 waves, 16 questions)
+
+Wave 1 has 6 questions (incl. the User-Story toggle); Waves 2-3 have 5 each. Before each wave, dispatch 2-3 Explore agents in parallel to pre-research options. Synthesize agent results into AskUserQuestion calls (max 4 questions per call, so split 4+1 or 3+2 per wave). Wave 1 carries the 6th User-Story toggle question, so split it 3+3.
+
+### Wave 1 — Core Decisions (6 questions)
+
+**Pre-wave agents (dispatch in a single message):**
+
+```
+Agent({ subagent_type: "Explore", description: "List available project archetypes",
+  prompt: "Run: ls $BASELINE_PATH/templates/
+  For each directory found, read any README or config file to get a one-line description.
+  Report as a numbered list: directory name — description." })
+
+Agent({ subagent_type: "Explore", description: "Research market context",
+  prompt: "Search online for market context related to the user's project idea.
+  Report: target audiences, competitor landscape, positioning opportunities.
+  Keep it to 5-10 bullet points with sources." })
+
+Agent({ subagent_type: "Explore", description: "Check ecosystem for conflicts",
+  prompt: "Run: ls ~/Projects/
+  List all repos. Identify any that overlap with or could serve as dependencies
+  for the proposed project. Report potential conflicts and reuse opportunities." })
+```
+
+**Questions:**
+
+1. **Project archetype** — Options from `$BASELINE_PATH/templates/` directory. Present agent findings. Choices: Dynamically list directories in $BASELINE_PATH/templates/. Present each as an option via AskUserQuestion.
+2. **Visibility** — internal (GitLab private), private (+ optional GitHub mirror), public/OSS (+ GitHub public + license).
+3. **Target audience** — Options informed by market research agent. User selects or provides custom.
+4. **User-Story-Schicht** — "User-Story-Schicht für dieses Feature erzeugen?" Immer fragen (kein Audience-Heuristik-Gate). Drei Antwortoptionen: **Ja (Als/möchte/damit)** — klassische Persona-Story-Form; **Ja (job-story)** — job-story-Form ("When [situation], I want [motivation], so I can [outcome]"); **Nein** — byte-identisches Status-quo-Verhalten. Bei einer der beiden "Ja"-Optionen emittiert die PRD eine optionale ## User Stories Sektion (je Story ein ↳ AC-Pointer) in der gewählten Form; bei "Nein" wird die Sektion vollständig weggelassen.
+5. **Core problem being solved** — Open-ended. Claude suggests structure if answer is vague.
+6. **GitLab group** — Discover available groups dynamically. Run `ls $BASELINE_PATH/templates/` for project types, and check for a groups config in `$BASELINE_PATH/config/` or use `glab group list` to discover GitLab groups. Present findings via AskUserQuestion.
+
+### Wave 2 — Technical Details (5 questions, dynamic per archetype)
+
+**Pre-wave agents:**
+
+```
+Agent({ subagent_type: "Explore", description: "Read archetype config",
+  prompt: "Read $BASELINE_PATH/templates/{archetype}/ — list all files, read key configs.
+  Report: default tech stack, available options, required decisions." })
+
+Agent({ subagent_type: "Explore", description: "Research tech stack best practices",
+  prompt: "Search online for best practices with the chosen tech stack ({archetype} + {key techs}).
+  Report: recommended patterns, common pitfalls, performance tips. 5-10 bullet points." })
+
+Agent({ subagent_type: "Explore", description: "Check ecosystem for shared patterns",
+  prompt: "Explore repos in ~/Projects/ that use similar tech stacks.
+  Report: shared libraries, common patterns, reusable modules." })
+```
+
+**Questions:**
+
+1. **Tech stack decisions** — e.g., Supabase vs alternative DB for nextjs-saas. Options informed by archetype config agent.
+2. **Design style** — For frontend archetypes: read `$BASELINE_PATH/templates/{archetype}/styles/` to discover available design variants. Dispatch agent to read baseline style configs. Skip for non-frontend archetypes (those without a `styles/` directory).
+3. **External integrations** — APIs, services, payment providers. Agent research informs common choices.
+4. **Performance requirements** — Latency targets, concurrent users, throughput expectations.
+5. **Security requirements** — Beyond baseline. Auth strategy, encryption, compliance needs (GDPR, SOC2).
+
+### Wave 3 — Business & Scope (5 questions)
+
+**Pre-wave agents:**
+
+```
+Agent({ subagent_type: "Explore", description: "Analyze archetype failure modes",
+  prompt: "Search online for common failure modes and risks for {archetype} projects.
+  Report: top 5 risks with probability/impact and standard mitigations." })
+
+Agent({ subagent_type: "Explore", description: "Check ecosystem dependency compatibility",
+  prompt: "For each ecosystem repo mentioned by the user as a dependency,
+  read its package.json/go.mod/pyproject.toml and CLAUDE.md (or AGENTS.md on Codex CLI).
+  Report: version constraints, API contracts, integration patterns." })
+
+Agent({ subagent_type: "Explore", description: "Research success benchmarks",
+  prompt: "Search online for comparable products/features to the user's project idea.
+  Report: typical KPIs, adoption curves, success metrics used by similar products." })
+```
+
+**Questions:**
+
+1. **MVP scope** — Shape Up appetite: 1 week / 2 weeks / 6 weeks. Frame trade-offs for each.
+2. **Success criteria** — SMART format (Specific, Measurable, Achievable, Relevant, Time-bound). Claude proposes draft from research, user refines.
+3. **Known risks and mitigations** — Present common risks from agent research. User confirms, removes, or adds.
+4. **Post-launch plan** — Monitoring strategy, rollback plan, feedback channels.
+5. **Ecosystem dependencies** — Other repos in the 17-repo ecosystem this project depends on or integrates with. Agent verifies compatibility.
+
+---
+
+## Phase 2: PRD Generation
+
+1. Read `prd-full-template.md` from this skill directory.
+2. Fill all 8 sections with gathered answers:
+   - **Section 1 (Executive Summary):** Synthesize core problem + audience + archetype into a concise project pitch.
+   - **Section 2 (Problem & Context):** From Wave 1 Q3 + Q5 (core problem) answers. Include market research findings.
+   - **Section 3 (Target Audience):** From Wave 1 Q3 + research agent output. Define 1-3 personas.
+   - **Section 4 (Solution & Scope):** From Wave 3 Q1 (appetite) + Wave 2 tech decisions. Explicit **In-Scope MVP** and **Out-of-Scope** lists. This section drives issue creation in Phase 4.
+   - **## User Stories (conditional):** Emit only when the User-Story-Schicht toggle ≠ "Nein"; one story per persona-goal (from Section 3 personas), each linking ≥1 acceptance criterion. Toggle = "Ja (Als/möchte/damit)" → classic Als/möchte/damit form. Toggle = "Ja (job-story)" → job-story form ("When [situation], I want [motivation], so I can [outcome]"). Omit the section entirely when toggle = "Nein" (byte-for-byte status quo).
+   - **Section 5 (Success Criteria):** From Wave 3 Q2. SMART table format: Metric | Target | Method | Deadline.
+   - **Section 6 (Technical Architecture):** From Wave 1 Q1 (archetype) + Wave 2 (tech stack, integrations). Include schema sketch if DB is involved.
+   - **Section 7 (Risks & Dependencies):** From Wave 3 Q3 + Q5. Table format: Risk | Probability | Impact | Mitigation.
+   - **Section 8 (Post-Launch Plan):** From Wave 3 Q4. Monitoring, rollback, feedback channels.
+3. Save PRD to `{plan-prd-location}/YYYY-MM-DD-{project-name}.md`.
+4. Dispatch reviewer per `prd-reviewer-prompt.md`. Max 3 iterations. Surface unresolved issues to user.
+
+---
+
+## Phase 3: Repo Setup
+
+After PRD is approved by user:
+
+### Step 1: Invoke setup-project.sh
+
+Map gathered answers to script input choices:
+
+```bash
+# Resolve input choices dynamically from setup-project.sh:
+# 1. Read $BASELINE_PATH/scripts/setup-project.sh
+# 2. Parse menu/select/case statements to find choice→name mappings
+# 3. Map user's selected archetype name → numeric choice for TYPE_CHOICE
+# 4. Map user's selected style name → numeric choice for STYLE_CHOICE (if applicable)
+# 5. Map user's selected group name → numeric choice for GROUP_CHOICE
+# Do NOT hardcode numeric mappings — they must be derived from the script.
+(
+  echo "$TYPE_CHOICE"    # e.g., "1" for nextjs-saas
+  echo "$STYLE_CHOICE"   # e.g., "1" for vega (only if nextjs-saas)
+  echo "$PROJECT_NAME"   # e.g., "my-cool-app"
+  echo "$GROUP_CHOICE"   # e.g., "1" for products
+  echo "y"               # confirm
+) | bash "$BASELINE_PATH/scripts/setup-project.sh"
+```
+
+### Step 2: Verify success
+
+Check exit code. Confirm repo exists:
+
+```bash
+glab repo view $GROUP/$PROJECT_NAME
+```
+
+### Step 3: Adjust visibility
+
+If visibility is not `internal` (the default):
+
+```bash
+glab repo edit --visibility private   # or --visibility public
+```
+
+For public/OSS, also configure GitHub mirror if applicable.
+
+### Step 4: Set branch protection
+
+```bash
+glab api -X PUT projects/:id/protected_branches \
+  -f name=main \
+  -f push_access_level=30 \
+  -f merge_access_level=30
+```
+
+### Step 5: Populate CLAUDE.md (or AGENTS.md on Codex CLI)
+
+Choose the project-instruction file appropriate to the platform that will operate the repo: `CLAUDE.md` for Claude Code / Cursor IDE, `AGENTS.md` for Codex CLI. Pick exactly one — never both. Add `## Session Config` section with fields derived from the planning session. Include at minimum:
+
+- `plan-baseline-path`
+- `plan-default-visibility`
+- `plan-prd-location`
+- Any project-specific config from gathered requirements
+
+### Step 6: Commit PRD
+
+Commit the PRD document to the new repo. Use a descriptive commit message:
+
+```bash
+git add docs/prd/YYYY-MM-DD-{project-name}.md
+git commit -m "docs: add project PRD from /plan new session"
+```
+
+### Step 7: Scaffold Steering Docs
+
+Create `.orchestrator/steering/` with three stub documents populated from planning answers.
+Steering docs give every future session stable product/tech/structure context without re-reading
+CLAUDE.md from scratch (consumed by session-start Phase 2.6).
+
+```bash
+mkdir -p .orchestrator/steering
+```
+
+**`product.md`** — mission + scope derived from Wave 1 (core decisions) and Wave 3 (MVP scope):
+- Mission: one sentence from the project pitch in PRD Section 1
+- Target users: from PRD Section 3 (personas)
+- In-scope features: from PRD Section 4 In-Scope MVP list
+- Out of scope: from PRD Section 4 Out-of-Scope list
+
+**`tech.md`** — stack + commands + constraints derived from Wave 2 (tech decisions):
+- Runtime stack: archetype + chosen tech stack + language/framework
+- Key commands: test, lint, typecheck, install (from archetype defaults)
+- Coverage thresholds: from archetype template if present, else leave as placeholder
+- Constraints: archetype-specific pitfalls (fill in or leave `_TODO_` for follow-up)
+
+**`structure.md`** — directory map + inventory from the scaffolded repo:
+- Top-level directory map: run `ls -1` and annotate each directory with its purpose
+- Inventory counts: fill in after `setup-project.sh` completes (skills/commands/agents as applicable)
+- Key files: entry points, SSOT files, main config files
+
+Write each file with real content from planning answers — never leave all three as pure stubs.
+At minimum, `product.md` must contain the mission sentence and the In-Scope list from the PRD.
+
+```bash
+git add .orchestrator/steering/
+git commit -m "chore: scaffold steering docs from /plan new session"
+```
+
+---
+
+## Phase 4: Issue Creation
+
+### Step 1: Derive Epic + sub-issues
+
+Source: PRD Section 4 (Solution & Scope).
+
+- **Epic title:** project name + brief description.
+- **Sub-issues:** One per MVP feature/scope item from the In-Scope list. Each issue gets a clear title, description referencing the PRD, and acceptance criteria.
+
+### Step 2: Auto-prioritize
+
+Score each issue using three factors:
+
+1. **Technical dependencies (highest weight):**
+   - DB schema before API, API before frontend, shared libs before consumers.
+   - Issues that block others → `priority:critical` or `priority:high`.
+2. **Business value (medium weight):**
+   - Core MVP features → `priority:high`.
+   - Nice-to-haves → `priority:medium` or `priority:low`.
+3. **Risk (tiebreaker):**
+   - Issues with identified risks from PRD Section 7 → bump up one level.
+
+### Step 3: Apply labels
+
+Use taxonomy from `setup-gitlab-groups.sh`:
+
+**Priority mapping for VCS labels:**
+| Categorization | VCS Label |
+|---|---|
+| P0 (critical path, blocking) | `priority:critical` |
+| P1 (high impact, needed soon) | `priority:high` |
+| P2 (medium, can wait) | `priority:medium` |
+| P3 (nice-to-have) | `priority:low` |
+
+Always use the `priority:<level>` format in VCS CLI commands, not P0/P1/P2/P3.
+
+- **type:** feature, enhancement, bug, chore, docs
+- **status:** `status:ready`
+- **area:** relevant domain label
+- **appetite:** 1w, 2w, 6w (matching MVP appetite)
+- **mvp-phase:** phase number if phased delivery
+
+### Step 4: Present for user confirmation
+
+Use AskUserQuestion to present the full issue structure:
+
+- Epic title and description
+- Sub-issues with: title, priority, labels, dependency links
+- User confirms, adjusts priority, removes issues, or adds missing ones
+
+### Step 5: Create via glab
+
+```bash
+# Create epic
+glab issue create --title "$EPIC_TITLE" --description "$EPIC_DESC" \
+  --label "type:epic,priority:$PRIORITY" --milestone "$MILESTONE"
+
+# Create sub-issues
+glab issue create --title "$ISSUE_TITLE" --description "$ISSUE_DESC" \
+  --label "type:feature,priority:$PRIORITY,status:ready,area:$AREA,appetite:$APPETITE"
+```
+
+### Step 6: Set dependency links
+
+For issues with technical dependencies, set `blocks`/`is-blocked-by` relationships:
+
+```bash
+# Issue #2 is blocked by Issue #1
+glab api -X POST projects/:id/issues/:issue2_iid/links \
+  -f target_project_id=:id \
+  -f target_issue_iid=:issue1_iid \
+  -f link_type=is_blocked_by
+```
+
+On HTTP 403 (non-Premium/Ultimate GitLab tier): fall back to `link_type=relates_to` + a body-ordering note — see gitlab-ops SKILL.md § "Issue Linking (`blocks` / `is_blocked_by`)".

package/skills/plan/mode-retro.md

@@ -0,0 +1,271 @@
+# Mode: `/plan retro` — Data-Driven Retrospective
+
+> Reference file for the plan skill. Read by SKILL.md when mode is `retro`.
+> Covers: automatic data collection, structured reflection (1-2 waves), improvement artifacts.
+
+---
+
+## Sub-Modes
+
+| Invocation | Behavior |
+|---|---|
+| `/plan retro` (no arg) | Full retro flow — Phases 1 → 2 → 3 |
+| `/plan retro vault-backfill` | Phases 1 → 1.6 (vault backfill), then exit — Phases 2-3 skipped |
+
+---
+
+## Phase 1: Data Collection (Automatic)
+
+Gather ALL data before asking questions. No user input. Present a dashboard when done.
+
+### 1.1 Session Metrics
+
+Read `.orchestrator/metrics/sessions.jsonl`. Extract per entry:
+
+- `session_type`, `started_at`, `completed_at`, `duration_seconds`
+- `effectiveness.completion_rate`, `effectiveness.planned_issues`, `effectiveness.completed`, `effectiveness.carryover`
+- `agent_summary.complete`, `agent_summary.partial`, `agent_summary.failed`, `agent_summary.spiral`
+- `waves[].role`, `waves[].agent_count`, `waves[].files_changed`, `waves[].quality`
+
+Compute aggregates:
+- Total sessions, average duration, session type distribution (deep/feature/housekeeping)
+- Average completion rate, total carryover rate (carryover / planned across all sessions)
+- Agent success rate (complete / total dispatched), spiral rate (spiral / total)
+- Most common wave roles, average files changed per wave
+
+If the file does not exist or is empty, note "No session metrics available" and continue.
+
+### 1.2 Git Analysis
+
+```bash
+git log --oneline -50
+git log --format="%H %s" --since="2 weeks ago"
+git log --format="%H" --since="2 weeks ago" | xargs -I{} git diff-tree --no-commit-id --name-only -r {} | sort | uniq -c | sort -rn | head -20
+```
+
+Record: total commits (2 weeks), frequency per day, top 20 change hotspots with counts.
+
+### 1.3 Open Issues
+
+Query via VCS CLI (per gitlab-ops skill):
+- **Overdue**: older than `stale-issue-days` without progress
+- **Blocked**: `blocked` label or `is-blocked-by` links
+- **Stale**: no activity in `stale-issue-days` days (default: 14)
+
+### 1.4 Trend Analysis
+
+Compare **last 5 sessions** vs **sessions 6-10**. Identify:
+- Completion rate trend (improving/declining/stable, >/< 5% threshold)
+- Session type mix shift
+- Recurring agent failures (same role failing across sessions)
+- Wave sizing patterns (agent count, wave count changing)
+
+If fewer than 10 sessions exist, use all available data and note limited sample.
+
+### 1.5 Data Summary Dashboard
+
+```
+## Data Summary
+- Sessions: N total (X deep, Y feature, Z housekeeping)
+- Completion: X% average (trend: up/down/stable)
+- Agent health: X% success, Y% spiral rate
+- Change hotspots: file1 (N changes), file2 (M changes)
+- Open issues: N total (X overdue, Y blocked, Z stale)
+```
+
+Omit sections where no data was found. Show trends only with 5+ sessions of comparison data.
+
+---
+
+## Phase 1.6: Vault Backfill (conditional sub-mode)
+
+> **Activation**: This phase runs ONLY when the user invokes `/plan retro vault-backfill`.
+> When invoked without the `vault-backfill` argument, skip this phase entirely and proceed to Phase 2.
+
+### Workflow
+
+**Step 1 — Read config**
+
+Read Session Config to obtain the `vault-integration.gitlab-groups` list. If not set, prompt the user to supply `--groups <CSV>` directly, or abort with a message.
+
+**Step 2 — Dry-run scan**
+
+```bash
+node scripts/vault-backfill.mjs --groups <CSV>
+```
+
+Captures stdout (per-repo JSON action records) and stderr (progress logging). Present the dry-run table to the user so they can review which repos would receive `.vault.yaml` stubs.
+
+**Step 3 — User choice (AskUserQuestion)**
+
+After the dry-run, present:
+
+1. **Apply all changes** → re-invoke with `--apply` (optionally `--out-dir <path>` to override staging dir)
+2. **Apply via headless manifest** → user provides manifest JSON path → invoke `--yes <path> --apply [--out-dir <path>]`
+3. **Skip backfill — proceed to Phase 2** → no writes, continue retro
+4. **Abort** → exit retro session
+
+**Step 4 — Log results to retro narrative**
+
+On apply, append per-repo results to Section 4 of the retro document so the artifact captures what was backfilled this session.
+
+If `vault-backfill` sub-mode was used, exit after this phase — Phases 2 and 3 are skipped.
+
+### CLI Flag Reference
+
+| Flag | Default | Description |
+|---|---|---|
+| `--groups <CSV>` | — | Comma-separated GitLab group paths to scan |
+| `--dry-run` | yes | Preview changes without writing (default behavior) |
+| `--apply` | off | Write `.vault.yaml` files to staging directory; review and copy into repos manually |
+| `--out-dir <path>` | `./.vault-backfill-staging` | Staging directory for `--apply` writes; files written to `<out-dir>/<group>/<repo>/.vault.yaml` |
+| `--yes <manifest.json>` | — | Headless mode — skip all interactive prompts; manifest is authoritative scope (no live API check) |
+| `--vault-dir <path>` | — | Override target directory for vault folder stubs |
+| `--verbose` | off | Emit detailed per-repo logging to stderr |
+
+> **Real apply writes to a staging directory.** User reviews the generated `.vault.yaml` files under `--out-dir`, then manually copies them into each repo (or scripts a follow-up push).
+
+### Headless Manifest Example
+
+```json
+{
+  "version": 1,
+  "manifest_date": "YYYY-MM-DD",
+  "gitlab_groups": ["infrastructure"],
+  "repos": [
+    {"id": 42, "path": "infrastructure/auth-service", "slug": "auth-service", "tier": "active", "visibility": "internal"},
+    {"id": 57, "path": "infrastructure/api-gateway", "slug": "api-gateway", "tier": "top", "visibility": "internal"}
+  ]
+}
+```
+
+### Exit-Code Interpretation
+
+| Code | Meaning | Retro action |
+|---|---|---|
+| 0 | Success — clean run (dry or apply, even if some repos skipped) | Log results, continue |
+| 1 | Validation error — bad CLI flags, missing `--groups` AND no Session Config groups, malformed manifest, missing `glab` CLI | Show error message, offer to abort or reconfigure |
+| 2 | Filesystem error — template not found, cannot write to `--out-dir` (EACCES, ENOSPC) | Show error, check `PROJECTS_BASELINE_DIR` / disk space, then retry |
+| 3 | GitLab API error — auth failure, rate limit, or ALL groups failed to resolve | Prompt user to check `GITLAB_TOKEN` and group paths, then abort |
+| 4 | Nothing to backfill — dry-run found no repos missing `.vault.yaml` (or all manifest entries marked `skip:true`) | Expected for Step 2 when fully synced; present table and proceed to Phase 2 |
+
+### Cross-References
+
+- Implementation: `scripts/vault-backfill.mjs` (C1)
+- Related drift detector: `skills/discovery/probes/vault-staleness.mjs`
+- Tracking issue: GitLab #241
+
+---
+
+## Phase 2: Reflection (1-2 Waves)
+
+### Pre-Wave Research
+
+Dispatch 3 Explore agents in parallel before Wave 1:
+
+```
+Agent({ subagent_type: "Explore", description: "Read session memory files",
+  prompt: "Read session memory files for retrospective context. On Claude Code: read session-*.md in ~/.claude/projects/<project>/memory/. On Codex CLI and Cursor IDE: skip this research — session memory is not available. Summarize: accomplishments, frustrations, scope changes, patterns." })
+
+Agent({ subagent_type: "Explore", description: "Analyze git log patterns",
+  prompt: "Analyze git log (2 weeks). Identify: large commits (>20 files), hotfix patterns, reverts, frequency distribution." })
+
+Agent({ subagent_type: "Explore", description: "Analyze open issues for themes",
+  prompt: "Read open issues from VCS. Categorize by type/area. Identify: recurring themes, repeated bugs, chronic carryover." })
+```
+
+Synthesize findings into Wave 1 questions.
+
+### Wave 1 — What Went Well / What Didn't (5 questions)
+
+Present via 2 AskUserQuestion calls (3+2 split).
+
+**Call 1:**
+
+1. **Highlights** — Top 3 data-backed successes. Options: `Confirm (Recommended)` | `Reorder/adjust` | `Add my own`
+2. **Blockers** — Top 3 data-backed problems with root causes. Options: `Confirm (Recommended)` | `Different root causes` | `Add blockers`
+3. **Carryover** — Unfinished issues from recent sessions (from `effectiveness.carryover` + `[Carryover]` prefixed issues). Options: `All still relevant (Recommended)` | `Cancel some` | `Reprioritize`
+
+**Call 2:**
+
+4. **Process** — Session structure assessment based on observed wave/agent patterns. Options: `Process is working well (Recommended)` | `Adjust wave/agent sizing` | `Change session type mix` | `Other`
+5. **Surprises** — Open-ended. Present data anomalies as starters. Options: `No surprises (Recommended)` | `Positive surprise` | `Negative surprise` | `Other`
+
+### Wave 2 — Improvements (Conditional)
+
+> Trigger if Wave 1 reveals: significant blockers (Q2), process issues (Q4 not "working well"), or user explicitly requests actions. Otherwise skip to Phase 3.
+
+**Call 1:**
+
+1. **Improvement actions** — Propose 3-5 concrete improvements. Each with: action, expected impact, effort. `multiSelect: true`. Example: `Add pre-commit type checks (Recommended)` — "Impact: reduce type errors ~50%. Effort: 1h."
+2. **Priority** — Rank selected improvements. Present in recommended order, user reorders.
+3. **Ownership** — When to tackle each. Options: `All in next session (Recommended)` | `Spread across sessions` | `Assign to specific sessions`
+
+**Call 2:**
+
+4. **Baseline changes** — Only if recurring issues (3+ sessions, same root cause). Propose specific template/script/rule changes. Options: `No changes needed (Recommended)` | `Apply suggested` | `Custom changes`
+5. **Session Config changes** — Propose config adjustments (e.g., `agents-per-wave`, `discovery-exclude-paths`, `stale-issue-days`). Options: `No changes needed (Recommended)` | `Apply suggested` | `Custom changes`
+
+---
+
+## Phase 3: Artifacts
+
+### 3.1 Retro Document
+
+1. Read `retro-template.md` from this skill directory
+2. Fill with Phase 1 data + Phase 2 answers
+3. Metrics section: auto-generated from `sessions.jsonl` — no user input for numbers
+4. Highlights/Improvement sections: reflect user-confirmed answers, not raw data
+5. Save to `{plan-retro-location}/YYYY-MM-DD-retro.md` (`mkdir -p` if needed)
+6. Present path to user for review via AskUserQuestion
+
+Before Phase 3.2, satisfy the PRD Commit Gate — see `SKILL.md` § Phase 5.5 (HARD-GATE). The gate applies to the retro document too: do not create improvement issues referencing an uncommitted retro. Skip this gate only if Wave 2 was not triggered (no issues will be created — see below).
+
+### 3.2 Improvement Issues
+
+Create one VCS issue per agreed improvement from Wave 2:
+- **Title**: `[Retro] <action description>`
+- **Labels**: `type:enhancement`, `priority:<from ranking>`, `area:<inferred>`
+- **Description**: action, impact, effort, link to retro document
+- Create via VCS CLI (per gitlab-ops skill)
+
+Skip if Wave 2 was not triggered.
+
+If issues were created and a 5+-action Epic wrapper was used (see `SKILL.md` § 6.1), follow `SKILL.md` § 6.6 to backlink the Epic IID into the retro document via a separate follow-up commit.
+
+### 3.3 Update Learnings
+
+Append new patterns to `.orchestrator/metrics/learnings.jsonl`. Use the same JSONL schema as session-end writes (see session-end/SKILL.md for canonical field reference):
+
+```json
+{
+  "id": "<uuid-v4>",
+  "type": "fragile-file|effective-sizing|recurring-issue|scope-guidance|deviation-pattern",
+  "subject": "<what the learning is about>",
+  "insight": "<the actual learning>",
+  "evidence": "<supporting data>",
+  "confidence": 0.5,
+  "source_session": "retro-YYYY-MM-DD",
+  "created_at": "<ISO 8601>",
+  "expires_at": "<ISO 8601 + learning-expiry-days (default: 30)>"
+}
+```
+
+Typical retro learning types:
+- `fragile-file` — hotspots correlating with failures or carryover
+- `effective-sizing` — wave/agent configs producing best completion rates
+- `recurring-issue` — problem patterns across multiple sessions
+- `scope-guidance` — session scope calibration insights
+- `deviation-pattern` — systematic plan deviations indicating planning gaps
+
+Before writing, check existing entries for matching `type` + `subject`. Confirm (+0.15 confidence, cap 1.0) or contradict (-0.2). New learnings start at 0.5.
+
+### 3.4 Optional Baseline Update
+
+If Wave 2 Q4 identified baseline changes:
+1. Propose specific modifications (file path, before/after content)
+2. Present via AskUserQuestion — user MUST confirm before any baseline modification
+3. Apply to `$BASELINE_PATH` (from Session Config `plan-baseline-path`)
+4. If declined, skip entirely
+
+Never modify baseline files without explicit user confirmation.