reflect

name	reflect
description	Session retrospective, operator coaching, harness postmortem, codification, and outer-loop cycle critique. Distills learnings into hooks/rules/skills, mutates the backlog from evidence, and emits harness-tuning suggestions to a branch. Learning engine of the outer loop. Use when: "done", "wrap up", "what did we learn", "retro", "reflect", "calibrate", "how could I have asked better", "prompt better", "teach me from this session", "what should I learn from this", "reflect on cycle", "cycle postmortem", post-/flywheel critique. Trigger: /reflect, /retro, /calibrate, /reflect cycle <cycle-ulid>.
argument-hint	[distill|calibrate|coach|tune-repo|append|cycle] [context]

/reflect

Structured reflection that improves both the harness and the operator.

Every finding becomes one of three things:

• a codified artifact
• a concrete coaching note
• an explicit justification for not codifying

Routing

Mode	Intent	Reference
distill (default)	End-of-session retrospective -> codified artifacts + operator coaching	references/distill.md
calibrate	Mid-session harness postmortem — fix the harness before the code	references/calibrate.md
coach	Deep dive on prompt quality, technical specificity, and concept building	references/coach.md
tune-repo	Refresh context artifacts, detect drift, update repo guidance	references/tune-repo.md
append	Append issue-scoped retro notes for /groom to consume later	references/retro-format.md
cycle	Bounded end-of-ship retrospective invoked by /ship — emit backlog mutations, harness-tuning proposals, and a cycle summary for the caller to apply	references/cycle.md

If the first argument matches a mode name, route to that reference. If no mode is provided, run distill.

Interpret natural-language requests as:

• "how could I have asked better", "teach me from this", "help me prompt better" -> coach
• "why did you do that", "you made the wrong call", "fix your instructions" -> calibrate
• "tune this repo", "refresh AGENTS", "context drift" -> tune-repo
• "reflect on cycle ", "postmortem this cycle", invocation from /ship (or transitively from /flywheel, which composes /ship) -> cycle

Responsibility Split

Reflection must separate three classes of failure:

1. Harness failure — the instructions, skills, tools, or codebase should have prevented the problem
2. Shared ambiguity — both sides left important constraints implicit
3. Operator-spec gap — the decisive information lived only in the user's head, so a tighter prompt would have reduced search space

Do not dump harness failures onto the user. If the repo, docs, or available context already contained the answer, that is not a prompt-quality critique.

Default Deliverables

Even in distill, inspect both lanes:

• System lane — instructions, skills, hooks, tests, CI, AGENTS.md, docs
• Operator lane — prompt rewrites, vocabulary, stack concepts, next-session moves

System codification is mandatory. Operator coaching is mandatory to assess, but only mandatory to emit when there is concrete, high-leverage feedback. Otherwise say so explicitly instead of manufacturing generic advice.

Use coach when the user wants the operator lane expanded into a deeper lesson.

Codification Hierarchy

When encoding knowledge, always target the highest-leverage mechanism:

Type system > Lint rule > Hook > Test > CI > Skill/reference > AGENTS.md > Memory

Cycle Mode Authority (outer-loop only)

cycle is a bounded invocation: /ship calls it at the end of the final-mile pipeline to capture learnings from the just-shipped ticket. /flywheel triggers it transitively by composing /ship. When invoked as cycle, reflect gains two privileges the other modes lack:

1. Backlog mutation proposals — may propose create, edit, consolidate, reprioritize, or delete on items in backlog.d/ (never backlog.d/_done/). Every proposal must cite an evidence ref from the cycle (commit, diff hunk, receipt path, log line).
2. Harness-tuning proposals — may propose skill/agent/hook/AGENTS.md/ CLAUDE.md edits. Reflect emits; it does not apply. The caller routes these to a harness branch for human review.

All other modes are read-only against backlog.d/ and the harness. If cycle cannot cite evidence for a mutation, downgrade it to a finding and let a human decide.

Invocation Contract

Triggered as /reflect cycle (aliases: /reflect --cycle <cycle-id>). The caller — normally /ship — passes this input packet:

• branch: name of the just-shipped feature branch (pre-merge).
• merged_sha: squash commit SHA now on master/main.
• closed_backlog_ids: list of IDs closed in this cycle (the closing set from /ship's trailer scan).
• referenced_backlog_ids (optional): Refs-backlog IDs noted but not closed.

A cycle-id identifies the retro artifact; derive it from merged_sha short form when the caller does not supply one.

Output Contract

Three categories. The two structured categories must be cleanly separable so the caller can apply them under different policies.

1. Backlog mutations (structured, machine-consumable). For each:

   • action: create | edit | reprioritize | delete
   • path: concrete backlog.d/<id>-*.md target
   • body: full file content for create, unified diff for edit, new priority for reprioritize, justification for delete
   • evidence: cycle ref justifying the mutation These are proposals. The caller (/ship) applies them to master via a follow-up commit and owns commit hygiene. Reflect does not stage, commit, or push these files itself.

2. Harness-tuning proposals (structured, machine-consumable). For each:

   • path: concrete file under skills/, agents/, harnesses/, AGENTS.md, CLAUDE.md, or a hook script
   • body: unified diff or full new-file content
   • evidence: cycle ref and codification-hierarchy justification Reflect must not write these to master. The caller routes them to a harness branch (/ship uses harness/reflect-outputs). A cycle run that mutates harness files on the current branch is a bug.

3. Cycle summary (human-readable narrative). What shipped, what was learned, what went well, what went poorly. Also written to the standard retro location (.groom/retro/<primary-id>.md or the .spellbook/reflect/<cycle-id>/ receipts dir, matching whatever convention the invoking repo already uses).

Invariants

• Harness mutations never land on master directly. Reflect emits; the caller routes to a harness branch. This is a hard cross-skill invariant also asserted in ship/SKILL.md.
• Backlog mutations are proposals, not auto-applied. Reflect does not git add / git commit on behalf of the caller.
• Session-retrospective mode still works standalone. distill, calibrate, coach, tune-repo, and append remain usable without cycle context — cycle is additive, not a replacement.

See references/cycle.md for judgment rules (consolidate vs split, when to escalate to a harness branch, evidence standards).

Gotchas

• Blaming the user for missing repo context: If the agent could have found it, it is a harness or retrieval failure.
• Giving generic prompt advice: "Be more specific" is not feedback. Name the missing constraint, example, acceptance test, or boundary.
• Skipping the operator lane: A retro that only mutates harness artifacts leaves user leverage on the table.
• Turning coaching into scolding: Start with what the prompt achieved, then show the stronger version and why it improves the search space.
• Teaching concepts without anchoring them to the session: Vocabulary only sticks when tied to a concrete decision, bug, or design tradeoff.