Reflect — step back and audit the work, not just the code
Trigger phrases: "reflect", "retro", "retrospective", "what did we miss", "step back", "introspect"
When
A nontrivial chunk of work just finished (a feature, a plan, a debugging session) and it's worth a deliberate
step back before committing or moving on. This is the meta-cognitive counterpart to [[iterate]]: iterate
drives a change to its exit test; reflect asks whether the exit test — and the approach behind it — was even
the right one. Skip it for a one-line, unambiguous change; there's nothing to reflect on.
Measure first, then remember
Run bash .claude/hooks/session-stats.sh (Bash tool, not PowerShell) before answering anything below, and open the pass with what it
reports. A retro built only on recall is an interview with the least reliable witness in the room: the model
reconstructs a tidy story from a context that has already been summarised, and the stretches where it span on a
failing approach are exactly the ones it remembers least. The script counts what actually happened — prompts,
tool calls, failing loops, near-duplicate prompts, interrupts, auto-compactions.
Treat each ⚠️ as a question to answer in the pass, not a verdict: a runaway loop asks what assumption kept
failing; a repeated prompt asks what context never landed; an interrupt asks where intent diverged; an auto
compaction asks what state was silently dropped. If the numbers and your recollection disagree, the numbers are
the record. If the script is missing, say the retro is recall-based —
do not present recall as measurement.
The pass
Ask each question honestly and write the answer, not a reassurance:
- Unverified assumptions — what did I take for granted that I never checked? Name each one and whether it
was actually confirmed (read the code / ran the flow) or just assumed.
- What got skipped — an edge case, an error path, a test, a doc update, a security/privacy angle. What was
silently dropped, and was that a conscious trade-off or an oversight?
- Right approach? — with hindsight, is this the direction we'd still pick? Did scope creep in? Is there a
simpler path we walked past ([[code-review]] altitude: could 200 lines be 50)?
- Evidence gap — which claims of "done" / "works" rest on having observed behavior vs. on inference?
An unobserved "it works" is a finding (see [[iterate]] / verify: drive the real flow).
- What I'd tell the next session — the one thing a fresh context most needs to know (feeds [[handoff]]).
Guardrails
- Findings, not code. Reflect surfaces gaps; the relevant specialist fixes them (a found gap re-enters
[[iterate]] or the author agent). It changes nothing itself.
- Honest, not performative. A retro that only confirms good work is a failed retro. If nothing is found,
say specifically why you're confident (what was verified), don't just assert it.
- Bounded. One pass, concrete findings, then act or close — not an open rumination loop.
- Token discipline ([[token-budget]]): a short ranked findings list to the main thread; detail to a file.
DoD (this skill's contribution)
session-stats.sh was run and every ⚠️ it raised is answered — or its absence is stated.
- Assumptions are labeled verified vs. assumed; unverified ones are flagged, not buried.
- Skipped items and any scope creep are named explicitly.
- Every "done/works" claim is traced to observed evidence or marked as inference.
- Findings are actionable (each maps to a fix, a follow-up, or an accepted trade-off).
1---2name: reflect-33description: |4 Retrospective self-audit after nontrivial work: unverified assumptions, skipped items, is-this-the-right-5 approach — findings, not code. The step-back counterpart to iterate's refine-to-done loop.6metadata:7 source: https://skillmd.com/skills/byerlikaya/reflect-38---910# Reflect — step back and audit the work, not just the code1112<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->13Trigger phrases: "reflect", "retro", "retrospective", "what did we miss", "step back", "introspect"1415## When16A nontrivial chunk of work just finished (a feature, a plan, a debugging session) and it's worth a deliberate17step back **before** committing or moving on. This is the meta-cognitive counterpart to [[iterate]]: iterate18drives a change *to* its exit test; reflect asks whether the exit test — and the approach behind it — was even19the right one. Skip it for a one-line, unambiguous change; there's nothing to reflect on.2021## Measure first, then remember22Run **`bash .claude/hooks/session-stats.sh`** (Bash tool, not PowerShell) before answering anything below, and open the pass with what it23reports. A retro built only on recall is an interview with the least reliable witness in the room: the model24reconstructs a tidy story from a context that has already been summarised, and the stretches where it span on a25failing approach are exactly the ones it remembers least. The script counts what actually happened — prompts,26tool calls, failing loops, near-duplicate prompts, interrupts, auto-compactions.2728Treat each ⚠️ as a **question to answer in the pass**, not a verdict: a runaway loop asks *what assumption kept29failing*; a repeated prompt asks *what context never landed*; an interrupt asks *where intent diverged*; an auto30compaction asks *what state was silently dropped*. If the numbers and your recollection disagree, the numbers are31the record. If the script is missing, say the retro is recall-based —32do not present recall as measurement.3334## The pass35Ask each question honestly and write the answer, not a reassurance:361. **Unverified assumptions** — what did I take for granted that I never checked? Name each one and whether it37 was actually confirmed (read the code / ran the flow) or just assumed.382. **What got skipped** — an edge case, an error path, a test, a doc update, a security/privacy angle. What was39 silently dropped, and was that a conscious trade-off or an oversight?403. **Right approach?** — with hindsight, is this the direction we'd still pick? Did scope creep in? Is there a41 simpler path we walked past ([[code-review]] altitude: could 200 lines be 50)?424. **Evidence gap** — which claims of "done" / "works" rest on having *observed* behavior vs. on inference?43 An unobserved "it works" is a finding (see [[iterate]] / verify: drive the real flow).445. **What I'd tell the next session** — the one thing a fresh context most needs to know (feeds [[handoff]]).4546## Guardrails47- **Findings, not code.** Reflect surfaces gaps; the relevant specialist fixes them (a found gap re-enters48 [[iterate]] or the author agent). It changes nothing itself.49- **Honest, not performative.** A retro that only confirms good work is a failed retro. If nothing is found,50 say specifically *why* you're confident (what was verified), don't just assert it.51- **Bounded.** One pass, concrete findings, then act or close — not an open rumination loop.52- **Token discipline** ([[token-budget]]): a short ranked findings list to the main thread; detail to a file.5354## DoD (this skill's contribution)55- `session-stats.sh` was run and every ⚠️ it raised is answered — or its absence is stated.56- Assumptions are labeled verified vs. assumed; unverified ones are flagged, not buried.57- Skipped items and any scope creep are named explicitly.58- Every "done/works" claim is traced to observed evidence or marked as inference.59- Findings are actionable (each maps to a fix, a follow-up, or an accepted trade-off).