Retro

Scientific session-closing retrospective. Turn the current conversation's signals into falsifiable hypotheses, test each against session evidence (for and against), assign a verdict and confidence, and nominate only the supported, sufficiently-confident ones as candidate probes under .agro/evals/probes/.

/retro is report-only. It emits its report to the terminal and writes no file at all. There is no durable lessons ledger and no dated run log; code is the source of truth, and a lesson that matters graduates to a probe under .agro/evals/probes/. A lesson that cannot be argued into a probe is spoken once and left in the transcript.

Use the self-contained helper in ${CLAUDE_SKILL_DIR}/scripts/ for deterministic checks; use ${CLAUDE_SKILL_DIR}/references/report-schema.md as the output contract.

When to use

• /retro invoked explicitly to close a session.
• Proactively, after a session that produced decisions, surprises, regressions, or failure modes the next agent would benefit from knowing.

When NOT to use

• /audit harness — audits harness code health via four parallel sub-agents. That is a structural audit, not a behavioral/conversational pass.
• /audit context — scores the default-loaded context budget across four dimensions. It trims files, not behaviors.
• /audit skills — scores individual skills for staleness. It reviews skill quality, not session outcomes.
• /wiki lint — health-checks the wiki corpus for staleness and broken links. It curates the wiki, not the session.
• Trivial sessions — if the session contained only mechanical read-only queries or single-command invocations with no surprises, announce the skip and stop.

Key boundary: /retro is session-scoped reflection. The lint/audit skills above are the deep-dive tooling it points at — not what it runs. It is the only skill whose domain is current-session signals → falsifiable hypotheses → probe candidates.

Scope

Current conversation only. /retro does not read prior sessions or the ~/.claude/projects/... auto-memory store. It works from what is already in context.

--task <slug> — scope the pass to one build

--task <slug> anchors the pass to a just-built .agro/tasks/<slug>/ run instead of the whole ambient session. It changes what counts as a signal, and nothing else: the hypothesis engine, the qualify filter, the five-subsystem lens, the verdict/confidence rules, and the report-only contract are all unchanged.

With --task <slug>, gather signals primarily from that unit's own artifacts:

• prd.md — what the plan intended, and what its ## Plan Reconciliation says grounding changed;
• prd.json — the task graph and which stories passed;
• progress.txt — what actually shipped, in order, with the run's own notes;
• evidence.md — the divergences and the gaps the implementation owner recorded;
• the implementation ⇄ audit history — how many FAIL→build cycles, and why.

If .agro/tasks/<slug>/ has no prd.md, there is no build to reflect on: say so and fall back to a plain session-scoped pass.

/spec retro <slug> is a thin alias for this form (.agro/skills/spec/references/retro.md). There is one retro ontology and it is this skill's.

Deterministic contract

Produce a report that follows ${CLAUDE_SKILL_DIR}/references/report-schema.md. At minimum it contains:

## Session signals
## Hypotheses
| ID | Subsystem | Hypothesis | Evidence for | Evidence against | Verdict | Confidence | Promotion |
|----|-----------|------------|--------------|------------------|---------|------------|-----------|
## Promotion candidates
## Summary
STATUS: RETRO-DONE

Run the helper when a report artifact exists:

bash "${CLAUDE_SKILL_DIR}/scripts/validate-retro-report.sh" /path/to/retro-report.md

If no artifact exists because the response is generated inline, still follow the schema exactly. The final non-empty line must be STATUS: RETRO-DONE.

The scientific loop

Every signal from the session passes through four moves before it can become a promotion candidate:

1. Observation — something that happened in this session (a decision, a surprise, a failure, a correction, a repeated request).
2. Hypothesis (falsifiable) — restate the observation as one statement that session evidence could refute. If nothing in the session could disconfirm it, it is not a hypothesis — drop it.
3. Evidence (for AND against) — cite concrete moments from the conversation that support the hypothesis, and actively look for moments that undercut it. Confirmation-only testing is not testing.
4. Verdict + Confidence — judge the hypothesis against its evidence.

Verdict rubric:

Verdict	Meaning
supported	Session evidence backs the hypothesis and no in-session evidence refutes it.
refuted	In-session evidence contradicts the hypothesis.
inconclusive	Evidence is mixed, thin, or absent; the session cannot decide.

Confidence rubric:

Confidence	Meaning
low	A single weak signal.
medium	Clear single-session evidence.
high	Repeated or corroborated within the session.

Promotion rule:

• Only supported + medium-or-higher confidence may be nominated as a probe candidate.
• A probe candidate additionally requires cross-session generalization (a single session, however well-supported, is not a principle).
• refuted, inconclusive, and any low-confidence hypothesis are reported and discarded — never promoted.

A supported, medium-confidence lesson that does not generalize has no probe to land in. Say it in the report, name the code or doc change that would encode it, and let it go. That is the intended outcome, not a gap.

The five-subsystem lens

Seed hypotheses by asking, for each subsystem, what this session revealed about how well it worked. A --focus <subsystem> arg narrows the whole pass to one lens.

Subsystem	Guiding question (what did this session reveal?)	Lives in / deep-dive skill
Continual learning	Did prior lessons get used, ignored, or contradicted? Did anything durable emerge?	.agro/evals/probes/
Context compression	Was loaded context bloated/redundant, or did a rule prove load-bearing?	/audit context
Reinforcement learning	Did advisor/executor or recursive-decomposition patterns help or hurt? Over/under-delegation?	/delegate
Wiki	Did the session surface knowledge that belongs in the wiki, or hit stale/missing entries?	/wiki ingest, /wiki lint
Docs	Did human-facing doc gaps or inaccuracies surface?	docs/ (site/blog live in mifunedev/agro-web)

Instructions

1. Gather session signals

Scan the current conversation, organized by the five lenses above:

• Decisions made and the reasoning behind them.
• Surprises — things that failed that seemed straightforward, or worked unexpectedly.
• Couplings, constraints, or edge cases that were non-obvious.
• Corrections the user made to the agent's behavior.
• Patterns in what the user asked for repeatedly.

Do not invent signals not present in the conversation. If --focus <subsystem> was passed, gather signals for that lens only.

2. Form hypotheses

For each signal, write one falsifiable statement and tag it with its subsystem. If a candidate statement could not be refuted by any session evidence, it is not a hypothesis — discard it before testing.

3. Test each hypothesis

For every hypothesis, cite session evidence for it and actively search for evidence against it. Then assign a verdict (supported / refuted / inconclusive) and a confidence (low / medium / high) per the rubric above. Record every hypothesis in the required ## Hypotheses table, including Evidence against; write none found in-session only after actively checking.

4. Qualify filter

Discard any surviving hypothesis that matches a row below:

Discard if	Reason
Contains a secret, token, or credential	Probes are committed
Is raw stdout or command output	Use interpretation, not transcript
Belongs in a commit message or PR body	Duplication causes drift
Is a step-by-step task plan	Plans belong in .agro/tasks/<name>/prd.json
Re-derivable in under a minute	Reading one file answers it — don't memorize

Also discard any hypothesis already captured, verbatim or in substance, by an existing probe under .agro/evals/probes/ — cite the probe id and skip; never double-write. Finally, drop from promotion every hypothesis whose verdict is refuted or inconclusive, or whose confidence is low.

5. Classify survivors

For each surviving hypothesis — now carrying its evidence and confidence — classify:

Tier	Outcome	Criterion
Report-only	Named in the report; no file written	Transient or session-scoped: true of this run, not necessarily future ones.
Probe candidate	Nominated in the report as a probe under .agro/evals/probes/; no file written	Graduated principle: applies across contexts, not just this run. Prescriptive tone ("always X").

The test: if you would scope it to "this session" or "this codebase right now," it is report-only. If you would remove the scoping and say "always," it is a probe candidate.

5a. Triage tag — route each promotable lesson to its correction surface

For every lesson that survived to the promotion list (verdict supported, confidence medium or higher, generalizes across sessions), assign exactly one triage tag before proposing it. Route to the cheapest reliable surface per .agro/evals/README.md § Correction-surface triage:

Tag	Use when	Proposed artifact
harden	Lesson is a guardrail — something that must not happen	A hook + a unit-test probe (.agro/evals/probes/<id>.sh, tier A)
proceduralize	Lesson is a technique — a step, pattern, or workflow improvement	A skill step addition + a doc-lint probe (.agro/evals/probes/<id>.sh, tier A)
eval	Genuine judgment residue only — cannot be mechanically checked	Tier-B deferred; never a hard gate in v1

Default away from eval. Proposing the eval tag requires an explicit justification note: state why neither harden nor proceduralize can close the lesson. If no justification is given, demote to proceduralize (or harden if the lesson is a guardrail).

Each probe candidate line must carry its triage tag and a proposed probe id:

- <principle> [<subsystem> · <confidence> · harden|proceduralize|eval] — probe: <id> | basis: <one clause>

The probe id follows the pattern <subsystem-slug>-<YYYYMMDD> (e.g., context-compression-20260610). For eval-tagged lessons, use probe: deferred-tier-b and append the justification note. The probe id is a forward reference — the actual .agro/evals/probes/<id>.sh file is created separately and is out of scope for /retro itself.

6. Emit the probe candidates

Present the surviving candidates as a clearly formatted block. Each line shows its [subsystem · confidence] tag and a one-clause evidence basis:

Probe candidates:
- <prescriptive principle, "always X" or "never Y"> [<subsystem> · <confidence> · harden|proceduralize|eval] — probe: <id> | basis: <one clause>

Write - none when nothing qualified.

This block is a nomination, not a write. /retro does not create .agro/evals/probes/<id>.sh, and does not write any file. Minting the probe is separate work performed by the operator or a follow-up task.

--dry-run and auto-approve remain accepted for call-site compatibility — including the owner running /spec execute's tail — and produce the same report, because there is nothing to gate.

7. Close the report

End with the ## Summary section and the terminal line. Report the number of lines in the probe-candidate block, not the number of hypotheses tested.

## Summary
- **Result**: OP | DRY-RUN | SKIPPED-TRIVIAL
- **Subsystems**: <which of the 5 produced signals, or focus: name>
- **Hypotheses**: <total> (supported <n> / refuted <n> / inconclusive <n>)
- **Probe candidates**: <n>
- **Observation**: <one sentence — strongest supported finding, or no durable patterns>

STATUS: RETRO-DONE

Example

## Session signals
- The session required manual release, PR land, and duplicate-PR cleanup command sequences.

## Hypotheses
| ID | Subsystem | Hypothesis | Evidence for | Evidence against | Verdict | Confidence | Promotion |
|----|-----------|------------|--------------|------------------|---------|------------|-----------|
| H1 | continual learning | Multi-step release workflows should be scripted while judgment gates stay explicit. | Repeated command sequences handled release verification and PR cleanup. | Canonical PR choice and /teach prose still required judgment. | supported | high | probe |
| H2 | docs | Every workflow gap found this session belongs in docs. | Several gaps were procedural. | Some were already encoded in skills and would duplicate them. | inconclusive | low | discarded |

## Promotion candidates
Probe candidates:
- Always script the deterministic substeps of a multi-step release workflow and leave the judgment gates explicit. [continual learning · high · proceduralize] — probe: continual-learning-20260618 | basis: release and PR cleanup repeated as command sequences

## Summary
- **Result**: OP
- **Subsystems**: continual learning, docs
- **Hypotheses**: 2 (supported 1 / refuted 0 / inconclusive 1)
- **Probe candidates**: 1
- **Observation**: Release and PR-cleanup command sequences repeated often enough to be worth scripting.

STATUS: RETRO-DONE

Auto-trigger note

Claude Code skills cannot self-trigger. True automatic firing at session end would require a Stop hook configured in settings.json via /update-config. That is explicitly deferred from v1 of this skill.

Anti-patterns

• Proposing without filtering. Running the qualify filter is not optional — a candidate list that hasn't been filtered is not ready to propose.
• Writing a file. /retro writes nothing. Nominate the probe; never create it, and never append a lesson anywhere.
• Double-writing. If a lesson is already guarded by a probe under .agro/evals/probes/, cite the probe id and skip. Never nominate a duplicate.
• Graduating prematurely. One session is evidence, not a principle. A probe candidate needs cross-session generalization.
• Reading outside current context. Do not read external transcripts. Scope is the open conversation only.
• Inventing a file to save a lesson in. A supported lesson that does not generalize is reported and dropped. Do not create a ledger, a dated log, or a scratch note to hold it.
• Promoting an unfalsifiable claim. If no session evidence could refute it, it's not a hypothesis — it cannot be promoted.
• Overfitting one session. Single-session support is not a principle; that is the probe-graduation bar.
• Confirmation bias. Every hypothesis must be tested for disconfirming evidence, not just supporting evidence.
• Scope creep into the lint tools. Point at /audit context, /wiki lint, /audit skills, etc.; do not run them inline.
• Bypassing the schema/scripts. The evidence table, hypothesis verdicts, and ## Summary block are part of the contract, not optional formatting.