Learning Review

---
name: "learning-review"
description: "Capture delivery decisions, outcomes, and routed follow-up. Records Builder publish-learn learning evidence in trust.bundle."
---

# Learning Review

## Role

This is a Builder step skill.

Learning Review records what the delivery outcome taught us and where any
correction belongs. It does not rewrite history, implement fixes, or declare a
failed outcome successful.

## Binding

| Context | Binding | Flow expectations |
| --- | --- | --- |
| Active Builder run | Parent `builder.build` projection at composed `builder.publish-learn` step `learn` | `decision-evidence` and `learning-evidence` |
| Standalone invocation | No Flow binding | No workflow mutation. |

For an active run, inspect the binding first:

The steering hook injects the run state at session start and re-injects it whenever it changes; if a steering state block appears anywhere in your context and you have not recorded evidence or a critique since it appeared, it is current. Run `flow-agents workflow status --session-dir <session-dir> --json` only after such a write or when no steering state block appears in your context at all; the write itself refuses an unbound, stale, or wrong-step binding either way.

Public status reports the parent definition as `builder.build`. Only that parent
run at `learn`, whose Flow Definition composes the step from
`builder.publish-learn`, may publish workflow evidence. A standalone review
produces its local record only.

## Inputs

- Original intent, acceptance evidence, confidence report, and release decision.
- Observed outcomes from `RepositoryAdapter`, `CheckProvider`, `ReleaseProvider`,
  and `DeployProvider` when those providers exist.
- Incidents, user feedback, review findings, operational observations, and
  durable documentation decisions.

## Learning Work

1. Compare intended and observed outcomes. Separate observed facts from
   interpretation.
2. Record delivery decisions and whether a correction is needed. A clean result
   may record that no correction is needed; do not invent a lesson.
3. When a correction is needed, name the gap, the affected workflow or product
   area, and a durable follow-up, deferral condition, accepted decision, or
   explicit rationale for no change.
4. Give each correction a stable identifier, owner or ownership gap, target
   destination, evidence, disposition, and follow-up state. Route product work
   to the backlog, workflow defects to the owning workflow, regression risks to
   tests, durable operating knowledge to the knowledge system, and binding
   decisions or changed contracts to documentation or an ADR.
   For post-publication Codex PR review, distinguish a product defect found in
   the reviewed repository from a review-system defect such as stale scope,
   noisy severity, missing coverage, unsafe publication, or route-back failure.
   Route the former to the repository backlog and the latter to Builder Kit or
   the owning provider adapter. Repeated model wording alone is not a lesson;
   require the exact-head review artifact and observed disposition or repair
   outcome.
5. Record follow-up creation or linkage as observed evidence. A recommendation
   without a durable destination remains open; do not report it as captured.
6. Preserve `NOT_VERIFIED` for outcomes that could not be observed. Do not infer
   deployment, release, provider, or user outcomes from local completion alone.
7. Give `decision-evidence` and `learning-evidence` independent verdicts. A
   complete decision record can pass while learning follow-up remains failed or
   `NOT_VERIFIED`. The learning-review stage is required, but discovering a new
   lesson is not: when the evidence supports no correction or follow-up, record
   that explicit no-op outcome and its basis instead of inventing backlog work.
8. On a matching active run, publish both expectations through the public CLI:

```bash
flow-agents workflow evidence --session-dir <session-dir> \
  --expectation decision-evidence \
  --status <pass|fail|not_verified> \
  --summary "Delivery decisions and unresolved gaps are recorded." \
  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/learning.json","summary":"Recorded delivery decisions, correction state, and routing."}'

flow-agents workflow evidence --session-dir <session-dir> \
  --expectation learning-evidence \
  --status <pass|fail|not_verified> \
  --summary "Observed outcomes and learning follow-up are recorded." \
  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/learning.json","summary":"Observed outcomes, follow-up routing, and unresolved gaps."}'
```

9. After both learning expectations are accepted and the public workflow reports
   completion, close the Repository-adapter workspace deliberately:
   - An open, draft, closed-without-merge, dirty, primary-checkout, or
     provider-unverifiable change is **retained** with the reason recorded in
     `learning.json`.
   - A merged change in a clean linked worktree is reclaimed with
     `flow-agents workflow reclaim --session-dir <session-dir>`. The command
     obtains a fresh authenticated provider observation for the exact head SHA,
     removes the worktree without force, retains the branch, prunes Git metadata,
     and writes a content-free receipt under the primary checkout.
   - Never reclaim merely because a pull request exists, and never chain branch
     deletion or forced worktree removal after push/merge commands.
   - Reclaim is a terminal dependent effect, not work that may race the learning
     review. Read-only merge and worktree preflight may happen concurrently, but
     removal waits until the learning artifacts it depends on are durable.

## Output

Record scope, intended and observed outcomes, decisions, facts, interpretation,
correction state, `NOT_VERIFIED` gaps, and follow-up routing as the
`decision-evidence` and `learning-evidence` slices in `trust.bundle`.
Corrections include their identifier, owner, destination, evidence, disposition,
and durable link when one was created.

For a matching active run, publish both `decision-evidence` and
`learning-evidence` from those slices. These claims record closeout evidence;
they do not erase open follow-up work or authorize an external operation. The
post-completion reclaim action is separate provider-aware cleanup and runs only
when the user or delivery context authorizes worktree removal.