Session Retrospective

Adaptive end-of-session review that converts outcomes into durable process/context/tool improvements. Deep by default; light mode is used with --light or for tiny routine sessions. Produces retro.md alongside plan.md and lessons.md in the session artifact directory.

Quick Start

/retro [path] # adaptive (deep by default) /retro --deep [path] # full analysis with expert lens /retro --from-run [path] # internal flag when invoked by cwf:run

• path : optional override for output directory

• --deep : force full 7-section analysis (expert lens, learning resources, web search)

• --from-run : internal invocation context flag; enables compact report for run-chain orchestration

Workflow

0. Update Live State

Run:

bash {CWF_PLUGIN_DIR}/scripts/cwf-live-state.sh set . phase="retro"

1. Locate Output Directory

Resolution order:

• If [path] argument provided, use it

• Reuse .cwf/projects/ path already used in this session (plan.md/lessons.md writes)

• If reused session path date prefix (YYMMDD ) differs from today's local date, AskUserQuestion:

• Continue existing session directory (recommended for same logical session across midnight/day rollover)

• Start a new dated directory for today

• If user selects a new dated directory, run {CWF_PLUGIN_DIR}/scripts/next-prompt-dir.sh --bootstrap <title> , then copy plan.md and lessons.md from the previous session directory when present so retro context is preserved.

• If multiple candidates exist, AskUserQuestion with candidates

• Otherwise run {CWF_PLUGIN_DIR}/scripts/next-prompt-dir.sh --bootstrap <title>

1.1 Non-Interactive Fallback (Required)

If AskUserQuestion is unavailable/blocked, do not wait. Resolve path in this order: explicit [path] -> live.dir -> latest .cwf/projects/ -> bootstrap via {CWF_PLUGIN_DIR}/scripts/next-prompt-dir.sh --bootstrap retro-light . Record a short note (Fast path or Post-Retro Findings ) so the fallback choice is auditable.

1.2 Early Light Fast-Path Short-Circuit (Required)

If invocation includes --light , run deterministic fast path immediately after output-dir resolution (before evidence collection and large artifact reads):

bash {CWF_PLUGIN_DIR}/scripts/retro-light-fastpath.sh
--session-dir "{output-dir}"
--invocation "{invocation_mode}"
--lang "{user-language}"

Then validate retro stage gate immediately:

bash {CWF_PLUGIN_DIR}/scripts/check-run-gate-artifacts.sh
--session-dir "{output-dir}"
--stage retro
--strict

Rules:

• Determine invocation_mode with the same criteria as Section 3.1 before running this command.

• In non-interactive direct runs, stop after this short-circuit path succeeds.

• Do not call AskUserQuestion in this path.

2. Read Existing Artifacts

Skip this section when Section 1.2 completed and execution already ended in non-interactive light mode.

Before reading artifacts, run the evidence collector (it includes best-effort Codex session-log sync with timeout protection):

bash {CWF_PLUGIN_DIR}/scripts/retro-collect-evidence.sh --session-dir "{output-dir}"

Then read retro-evidence.md (if generated), plan.md , lessons.md , and cwf-state.yaml . Read AGENTS/adapter docs and project-context docs only when those files exist.

When running deep mode (or when user explicitly specifies a diff baseline/scope), generate coverage-contract artifacts before drafting narrative sections:

bash {CWF_PLUGIN_DIR}/scripts/retro-coverage-contract.sh
--session-dir "{output-dir}"
--base-ref "{retro_base_ref:-HEAD~1}"

Then cite at least:

• total changed file count (artifact name: "diff-all-excl-session-logs.txt")

• top-level breakdown (artifact name: "diff-top-level-breakdown.txt")

• historical lessons/retro primary corpus count (artifact name: "project-lessons-retro-primary.txt")

3. Select Mode

Parse the --deep flag from the invocation arguments.

If --deep is present: mode = deep (full 7 sections).

If --deep is absent: assess session weight to decide mode:

• Light (Sections 1-4 + 7): Only when --light is explicitly specified, OR session < 3 turns with routine/simple tasks (config changes, small fixes, doc edits)

• Default bias: Deep. Invoking retro is itself a signal that the session warrants analysis. Use --light to explicitly request lightweight mode when cost savings is desired.

3.2 Light Fast Path (Required for --light )

Reuse the command and gate in Section 1.2. Do not rerun unless retro.md is missing/invalid. In non-interactive runs, stop after fast path + gate. Do not call AskUserQuestion when fallback policy is sufficient.

3.1 Detect Invocation Context

Determine invocation context from arguments and live task:

• Run-chain invocation: --from-run present, or live task explicitly indicates cwf:run .

• Direct user invocation: all other cases.

Persist this as:

invocation_mode: run_chain | direct

4. Draft Retro

Draft everything internally before writing to file.

Light Mode Path

After fast path bootstrap, enrich sections 1-4 and 7 inline only if time/context budget allows. No sub-agents.

Deep Mode Path

Draft sections 1-3 inline (these require full conversation access), then launch parallel sub-agents in two batches.

Resolve session directory: Resolve the effective live-state file, then read live.dir .

live_state_file=$(bash {CWF_PLUGIN_DIR}/scripts/cwf-live-state.sh resolve)

session_dir: "{live.dir value from resolved live-state file}"

Apply the context recovery protocol to these files before launching each batch:

Batch Agent Output file

1 CDM Analysis {session_dir}/retro-cdm-analysis.md

1 Learning Resources {session_dir}/retro-learning-resources.md

2 Expert α {session_dir}/retro-expert-alpha.md

2 Expert β {session_dir}/retro-expert-beta.md

Stage-tier policy for deep mode outputs:

• Critical (hard gate): {session_dir}/retro-cdm-analysis.md

• Non-critical (soft gate): {session_dir}/retro-learning-resources.md , {session_dir}/retro-expert-alpha.md , {session_dir}/retro-expert-beta.md

For all outputs: bounded retry = 1 for missing/invalid files.

• Shared output persistence contract: agent-patterns.md § Sub-agent Output Persistence Contract.

Run slot preflight before each batch launch:

bash {CWF_PLUGIN_DIR}/scripts/agent-slot-preflight.sh --required 2 --json

• If preflight returns launch_mode=blocked , wait/close active agents and retry once.

• If it returns launch_mode=multi_batch , run the batch sequentially agent-by-agent.

• Otherwise keep the default parallel launch.

Batch 1 — launch with the preflight-selected mode (only for agents whose result files are missing or invalid):

• Agent A — CDM Analysis: subagent_type: general-purpose , max_turns: 16 . Read {SKILL_DIR}/references/cdm-guide.md , analyze Sections 1-3 summary + relevant cwf-state.yaml , write Section 4 content to {session_dir}/retro-cdm-analysis.md , append <!-- AGENT_COMPLETE --> .

• Agent B — Learning Resources: subagent_type: general-purpose , max_turns: 20 . Find 2-3 external resources using the Web Research Protocol in {CWF_PLUGIN_DIR}/references/agent-patterns.md , write Section 6 content to {session_dir}/retro-learning-resources.md , append <!-- AGENT_COMPLETE --> .

Wait for Batch 1 to complete. Read output files from session directory:

• {session_dir}/retro-cdm-analysis.md — CDM analysis (needed by Batch 2 experts)

• {session_dir}/retro-learning-resources.md — Learning resources

Gate behavior after Batch 1:

• If retro-cdm-analysis.md remains invalid after retry: hard fail deep retro.

• If retro-learning-resources.md remains invalid after retry: continue with warning and render Section 6 with explicit omission note.

• Record gate path in output (PERSISTENCE_GATE=HARD_FAIL or PERSISTENCE_GATE=SOFT_CONTINUE , or equivalent wording).

Batch 2 — launch with the preflight-selected mode (after Batch 1, only for agents whose result files are missing or invalid):

• Agent C — Expert alpha: subagent_type: general-purpose , max_turns: 20 . Read {CWF_PLUGIN_DIR}/references/expert-advisor-guide.md

• {SKILL_DIR}/references/expert-lens-guide.md , analyze Sections 1-4 summary (including CDM output), write to {session_dir}/retro-expert-alpha.md , append <!-- AGENT_COMPLETE --> .

• Agent D — Expert beta: subagent_type: general-purpose , max_turns: 20 . Same contract as Expert alpha; write to {session_dir}/retro-expert-beta.md , append <!-- AGENT_COMPLETE --> .

After Batch 2: read output files from session directory ({session_dir}/retro-expert-alpha.md , {session_dir}/retro-expert-beta.md ). Draft Section 5 with the required agreement/disagreement synthesis subsection, then draft Section 7 inline (capability/tool scan), then integrate all results into retro.md.

Gate behavior after Batch 2:

• If either expert file remains invalid after retry: continue with warning and render Section 5 from available expert output(s) plus explicit omission note.

• Record soft gate path in output (PERSISTENCE_GATE=SOFT_CONTINUE or equivalent).

Rationale for 2-batch design: Expert Lens depends on CDM results. Batch 1 produces CDM + Learning in parallel, Batch 2 runs experts after CDM is available.

Section 1: Context Worth Remembering

Use section-writing guidance from section-authoring.md.

Section 2: Collaboration Preferences

Use section-writing guidance from section-authoring.md.

Section 3: Waste Reduction

Use section-writing guidance from section-authoring.md, including mandatory 5 Whys depth for major waste signals.

Section 4: Critical Decision Analysis (CDM)

Use section-writing guidance from section-authoring.md.

Section 5: Expert Lens

Use section-writing guidance from section-authoring.md. Agreement/disagreement synthesis subsection remains mandatory in deep mode.

Section 6: Learning Resources

Use section-writing guidance from section-authoring.md.

Section 7: Relevant Tools (Capabilities Included)

Use section-writing guidance from section-authoring.md, including capability inventory, gap classification, and action path.

5. Write retro.md

Write to {output-dir}/retro.md using the format below.

Immediately enforce deterministic retro artifact gate:

bash {CWF_PLUGIN_DIR}/scripts/check-run-gate-artifacts.sh
--session-dir "{output-dir}"
--stage retro
--strict
--record-lessons

If this gate fails, do not mark retro complete. Fix artifacts/mode labeling first, then re-run the gate.

6. Link Session Log

Discover runtime logs under:

• .cwf/sessions/

• Prefer suffix files: {YYMMDD}-.claude.md , {YYMMDD}-.codex.md

• Also allow unsuffixed files: {YYMMDD}-*.md

Then:

• Filter out already-symlinked candidates.

• Read a sample of each candidate to verify it matches the current session.

• Ensure {output-dir}/session-logs/ exists.

• For each verified log, create a relative symlink: ln -s "{relative-log-path}/{filename}" "{output-dir}/session-logs/{filename}"

• If no candidates or directories do not exist, skip silently.

7. Persist Findings

retro.md is session-specific. Persist findings to project-level improvements with a required ownership check before applying the eval > state > doc hierarchy.

7.0 Ownership Gate (Required, before tiering)

For each finding, classify ownership first:

• owner=repo — the fix belongs to this repository's local artifacts/policies.

• owner=plugin — the fix belongs to CWF plugin/runtime/shared tooling behavior.

Then set apply layer deterministically:

• owner=repo -> apply_layer=local

• owner=plugin -> apply_layer=upstream

Required metadata for every persist proposal:

• owner

• apply_layer

• promotion_target

• due_release

• evidence (command output, artifact path, or session-log line)

Routing rules:

• owner=repo : continue with tiering and local target updates.

• owner=plugin : do not propose local AGENTS/doc edits as the primary fix. Output an upstream backlog item (issue/patch target under plugins/cwf/ or related shared runtime files). Local edits are allowed only as clearly marked stopgaps.

• If ownership is ambiguous: default to owner=plugin , state uncertainty explicitly, and avoid adding repo-local policy noise.

• Keep durable behavior contracts in AGENTS/runtime adapters. Keep next-session.md delta-focused; do not move global contracts there.

After ownership routing, evaluate enforcement mechanisms strongest-first:

Tier 1: Eval/Hook (deterministic) — Can a script/hook catch this?

• check-session.sh / session_defaults for missing artifacts

• PreToolUse/PostToolUse hook for tool usage patterns

• Lint rule for style enforcement

Tier 2: State (structural) — Does this change workflow state?

• cwf-state.yaml schema (new artifacts, stage transitions)

• session_defaults (new always/milestone artifacts)

Tier 3: Doc (behavioral, last resort) — Only for judgment calls

• project-context.md for architectural patterns

• AGENTS.md or runtime adapter docs only for rules that can't be automated

Per-section persist actions:

• S1 Context → project-context.md (Tier 3 — context is inherently behavioral). Offer to append new context.

• S2 Collaboration → Classify owner first, then evaluate tier. AskUserQuestion "Apply?" for AGENTS.md/adapter changes only when owner=repo .

• S3 Waste / Root causes → For each 5 Whys structural cause, present: "Finding: X. Owner: {repo|plugin}. Apply layer: {local|upstream}. Recommended tier: {1|2|3}. Mechanism: {specific change}. Evidence: {concrete trace}." Right-placement check: AGENTS.md (or runtime adapters) for behavioral rules, project-context.md for architectural patterns, protocol/skill docs for process changes.

• S4 CDM → Key lessons through tiers (most → Tier 3 project-context.md ).

• S7 Tools → For owner=repo , AskUserQuestion "Implement now?". For owner=plugin , AskUserQuestion "Queue upstream issue/patch now?".

Expert Roster Maintenance (deep mode only, when Section 5 was produced):

• Extract expert names from Section 5 (Expert Lens) output

• Follow the Roster Maintenance procedure in {CWF_PLUGIN_DIR}/references/expert-advisor-guide.md (including the retro-specific gap analysis step)

• Report changes to the user in the retro output (Section 5 or post-section note) for visibility

8. Direct Invocation Report (Mandatory)

After writing retro.md , always report outcomes to the user.

If invocation_mode=direct (user-triggered /retro or cwf:retro ):

• Provide Retro Brief with 4-6 bullets:

• session objective/result

• top waste/root-cause signal

• most important CDM lesson

• critical tool/capability takeaway

• Provide Persist Proposals with 2-5 concrete items:

• Finding

• Owner (repo , plugin )

• Apply layer (local , upstream )

• Promotion target (gate/script/doc/backlog endpoint)

• Due release (or due date)

• Recommended tier (Eval-Hook , State , Doc )

• Evidence

• Target file/script (local) or upstream backlog target (plugin)

• Apply-now recommendation

• Ask whether to apply persist proposals now:

• repo-owned items: apply locally now? (yes/no)

• plugin-owned items: queue upstream issue/patch now? (yes/no)

If invocation_mode=run_chain :

• Provide compact 2-3 bullet completion report (pipeline continuity first), and include at least one concrete takeaway (waste/root-cause signal, CDM lesson, or next action).

• Include a short Persist Proposals mini-list with 1-2 concrete items that each state owner/apply-layer/target (file or backlog). If no actionable item exists, state that explicitly.

• Do not ask apply-now questions in run-chain mode; keep this report informative and hand off execution decisions to downstream run/ship flow.

9. Post-Retro Discussion

The user may continue the conversation after the retro. During post-retro discussion:

• Update retro.md — append under ### Post-Retro Findings

• Update lessons.md with new learnings

• Ownership check first — for each new learning, classify owner /apply_layer , then evaluate through eval > state > doc.

• If owner=plugin , append an upstream backlog note instead of adding repo-local policy prose.

• For deep retro lessons, include metadata lines:

• • Owner:
    repo|plugin``
• • Apply Layer:
    local|upstream``
• • Promotion Target:
    ...``
• • Due Release:
    ...``

• If plugin code was changed, follow normal release procedures (version bump and release note updates in README/docs as needed)

Do not prompt the user to start this discussion.

Output Format

Use canonical templates from section-authoring.md for both light/deep modes.

Rules

• Never duplicate content already in lessons.md.

• Be specific — cite session moments, not generic advice.

• Keep each section focused; if there is no meaningful signal, state that briefly.

• AGENTS.md/runtime adapter changes require explicit user approval.

• Use the deterministic gate checklist in retro-gates-checklist.md for deep-mode artifacts, persistence tiering, and direct-invocation reporting requirements.

• For Section 5 in deep mode, use {SKILL_DIR}/references/expert-lens-guide.md and include the mandatory agreement/disagreement synthesis subsection.

• Language override: retro.md and deep-mode companion outputs are written in the user's language.

References

• {SKILL_DIR}/references/cdm-guide.md — CDM probe methodology and output format

• {SKILL_DIR}/references/expert-lens-guide.md — Retro-specific expert lens constraints and output format

• section-authoring.md — Section 1-7 writing guidance and canonical light/deep output templates

• retro-gates-checklist.md — Deterministic retro artifact gates and reporting checklist

• expert-advisor-guide.md — Expert identity, grounding, selection, and retro mode format

• agent-patterns.md — Shared agent orchestration patterns