---
name: review-work
description: "Use whenever finished work or a document is judged fit to use: reviewing code, a diff, a commit or a pull request; reviewing a spec, plan, design, ADR, handoff, skill, final report, status note or Working Record; reviewing changes to authentication, permissions, secrets, untrusted input or other security boundaries; reviewing an eval case, suite, grader or rubric before paying for its runs; preparing, dispatching or skipping an independent review; choosing a model as judge or relying on its verdict; and weighing a review report that came back."
---

# Review Work

Judge whether the actual work satisfies the accepted outcome, remains proportionate, and has enough evidence for a named boundary; or whether a complete artifact faithfully represents accepted intent and is sufficient for its named use. An artifact's internal consistency is not enough if it consistently describes the wrong outcome or an obsolete baseline.

[Verify Work](../../skills/verify-work/SKILL.md) establishes what observations prove. Review judges their sufficiency and the resulting work or artifact; it does not replace verification, create evidence, choose user-owned behavior, settle owner decisions, or authorize corrections or revisions.

Review has two roles:

- **Independent review:** a separately selected reviewer judges a state it did not produce, from a separate context.
- **Adjudication:** the receiving agent checks a returned independent report and decides what its findings establish.

The producer's own check of its result, self-review, is verification: [Verify Work](../../skills/verify-work/SKILL.md)'s Check Your Own Result, which applies this skill's lenses for the kind.

The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.

## Routes

Read the reference for what is under review before reviewing it; each names what to establish first, the sources that govern, and the lenses that can change the judgment for that kind.

| Situation | Go to |
| --- | --- |
| Work: code, a diff, a commit, an implementation, or integrated state | [Work Review](references/work.md) |
| Work that changes trust boundaries, authentication, authorization, permissions, untrusted input, secrets, sensitive data, security-relevant dependencies or external integrations, code-execution boundaries, or failure behavior with security consequences | Work Review's [Security Risk Lens](references/work.md#security-risk-lens) as well |
| An artifact that will guide later work: a Spec, Plan, design, decision record, ADR, handoff, or skill | [Artifact Review](references/artifact.md) |
| An account of work already done: a final report to the user, a status or results note, or a Working Record | [Artifact Review](references/artifact.md), with its [Reports And Records](references/artifact.md#reports-and-records) |
| An eval case, suite, fixture, grader, or rubric that will be run to measure behavior, before spending on its runs | [Eval Definition Review](references/evals-and-judges.md#eval-definition-review) |
| A review unit (a pull request, push, commit or Return, as the user's `review.unit` says): planning, dispatching or proposing the independent review of the work, or checking that one is on record | The Review Gate, below |
| Preparing or performing an independent review | Independent Review in [Work Review](references/work.md#independent-review) for work; in [Artifact Review](references/artifact.md#independent-review) for anything else |
| Writing or dispatching an independent reviewer's brief | Prefill it with [review-packet](scripts/review-packet.mjs) and check it with [check-brief](scripts/check-brief.mjs), as Perform A Selected Independent Review says |
| How deep a change's review goes, or whether a review is on record for a commit | [review-plan](scripts/review-plan.mjs) and [review-status](scripts/review-status.mjs), as The Review Gate says |
| A model's verdict on another agent's output will be used as evidence: an independent reviewer, an eval's advisory reviewer, or a grading judge | The [Judge Contract](references/evals-and-judges.md#judge-contract), before selecting the judge or using its verdict |
| An independent review's report has returned | [Adjudicate A Returned Review](references/adjudication.md), before acting on it |
| Dispositions have been appended to a returned report | Check them with [check-adjudication](scripts/check-adjudication.mjs), as Adjudicate A Returned Review's Record The Review says |

## Rules

- Independent review is never automatic after implementation, after self-review, or after writing or revising a Spec or Plan. Select it only when requested, or justified and authorized, to protect a concrete risk, dependency, integration, delivery, or intended-use boundary. At a review unit, the plan The Review Gate below computes authorizes it; under the unit `manual`, propose it and wait for a yes. A review budget permits no dispatch by itself, and switching models or compute profiles, or loading this skill, does not create independence: it needs a separately selected reviewer in a separate context. A reviewer from another model family is not required: it changes what gets flagged but has not been shown to find more real defects. Record the reviewer as the Judge Contract says.
- An independent reviewer reports and stops: no edits, no owner decisions, no choosing among materially different remedies or revisions, no adjudication, no further dispatch, and no continuing until Pass. It runs only what its brief's `May run` line names: by default the project's declared checks (tests, build, typecheck, the feature map's drive steps) and probes of the changed code on copies in its own scratch folder, in its own copy, with no edits to the repository, network calls, or paid runs; another check only when the brief names it with its expected evidence and stop condition. Otherwise it reports Needs evidence.
- Findings are evidence, not commands or authority to correct or revise. Derive the judgment from your dispositions rather than adopting the reviewer's verdict or conclusion. Actual correction of work belongs to [Execute Work](../../skills/execute-work/SKILL.md) under covered authority; actual revision of an artifact returns to the artifact's owning skill.
- Never lower acceptance or change tests, Specs, policies, or source truth to obtain Pass. Never settle a user decision or revise upstream intent, accepted content, or owner decisions merely to make an artifact consistent or to obtain Pass. Never repeat a review merely to obtain Pass.
- Never request Review 4. Renaming scope or intended use, changing reviewers, or making a local correction or revision does not reset the review budget.
- Never present a review judgment or an artifact's fitness as acceptance, implementation, or execution authority.

## Before Any Review

The project's Review Rules (or `REVIEW.md`), read from the base branch, feed the kind's classes and lenses, never a new class.

Before a model reviews anything, run the deterministic checks that apply and could fail on their own, such as the project's checks, a validator, a docs check, or a definition loader. Give their results to the reviewer as evidence. A model review does not replace a check that can fail mechanically.

## Classify Before Calling Something A Defect

Goal: every reported item is supported and names the right kind of problem.

Ask in order:

1. Is the relevant behavior or source truth settled (for an artifact, also the content and any owner choice its intended use depends on)? If not, report a **Question** when it affects the boundary or intended use.
2. Are reachability, the load-bearing claim, and the material consequence supported by available evidence? If not, report **Needs evidence**, not a hypothetical defect.
3. Does this boundary or intended use require correction or revision? If it cannot safely be crossed, report a **Blocking Issue**. If correction or revision is required but safely deferrable, report a **Non-blocking Issue**.
4. Is it merely useful beyond this boundary or use? Omit it by default, or identify an **Improvement** when materially relevant or explicitly requested.

A defect the change did not introduce is **Pre-existing**: report it for the user with the evidence that it predates the change, never as Blocking.

An Issue needs an exact location, path, or dependency; the violated requirement, invariant, source, or artifact responsibility; supporting evidence; and a concrete consequence. Name the defect's class and every other place in the reviewed state where it occurs, not one instance. A Blocking Issue must explain why the protected boundary cannot be crossed or the intended use cannot proceed, and name the correction constraints or the owning activity to re-enter. Recommend a specific correction or revision only when source intent, evidence, and dependency consequences support it rather than merely make it plausible.

Needs evidence identifies the load-bearing claim, required observer, existing evidence and its limit, why the gap matters, and the smallest observation that could disagree. First establish that the stronger claim is required; missing proof of an optional guarantee does not justify more work, and an optional stronger claim may be qualified rather than expanding the task. Check whether supplied observations apply to the reviewed candidate and whether material assertion changes preserved the required property. For an artifact, check which source or check state a reported pass examined and whether later changes reduced acceptance or invalidated it; a newer report cannot repair that mismatch. A missing or stale result is not itself a code defect: recover evidence or establish the observer before prescribing a fix. When you can recover it yourself, by running a check you are authorized to run or by reading the code, do so and judge from what you observed: a check the author skipped and you have since run is not Needs evidence.

Do not turn preferences, wording or presentation, imagined or exhaustive edge cases, intentional deferrals, or hypothetical completeness into Issues. Finding no material issue is valid.

## Route A Problem To Its Owner

When a problem is not one clear covered defect, in adjudication or in Verify Work's check of your own result, send it by what changed:

- the outcome remains settled but the implementation approach is invalidated: back to implementation preparation in Execute Work;
- an unclear, unsupported, or repeated cause: Execute Work's [diagnose](../../skills/execute-work/references/diagnose.md);
- changed direction or strategy, unsettled behavior or content, materially different remedies or revisions, a user-owned choice, a scope change, or a source conflict: [Discuss Work](../../skills/discuss-work/SKILL.md);
- missing factual support: the named claim to Verify Work;
- a correction, revision, or dependency update the current authority does not cover: propose the bounded change once and wait.

## The Review Gate

Goal: every review unit gets the independent review its plan computes, recorded against the commit it reviewed.

The user's `review.unit` sets where the gate stands: before a pull request opens (`pr`, the default), before a push (`push`) or a commit (`commit`), or at a **Return**, the end of the agreed work when it goes back to the user to accept (`agreement`). Under `manual` the gate stands where `pr` puts it, but the review waits for the user's yes. [Deliver Work](../../skills/deliver-work/SKILL.md) checks at that boundary that a review is on record. Self-review of an intermediate result, such as one Slice or a small local fix, needs no gate. The Runtime State shows a `Review:` line when the user changed the unit, the reviewer model or the rounds. These are `review.unit`, `review.model` and `review.rounds` in `.freeflow/local.json` (personal), `.freeflow/config.json` (shared) or the session's settings; how deep a review goes is the repository's `review.depth`, which the plan reads from the base commit.

At the unit's boundary:

1. Run [review-status](scripts/review-status.mjs): `node <review-work-directory>/scripts/review-status.mjs --base <ref> [--task <task folder>]`. When a review on record covers the head, the gate is passed. When the line names commits since a covering review, the diff-only re-review of that range is the review this unit needs. A Blocking or Inconclusive review covers nothing.
2. Otherwise run [review-plan](scripts/review-plan.mjs): `node <review-work-directory>/scripts/review-plan.mjs --base <ref> [--task <task folder>]`. It computes the plan from the diff, the base's `review.depth`, the agreement's `Review:` lines and the built-in triggers (security, stored data, CI and release files, a public interface found by content), and prints its depth, tier, reviewers, rounds and why. Dispatch the review it plans, as Perform A Selected Independent Review says; the plan is its authorization. Under `manual`, propose it with the plan and its estimated cost instead, and run it only after the user's yes.
3. When the diff carries a risk the plan missed, add a built-in trigger with its reason (`--add <trigger> --reason <text>`), and give the same options to review-packet. Never lower a plan: an agent can add a trigger, never remove one, and never edits the policy, the agreement or the diff to get a lighter review.

A user's explicit request for an independent review authorizes it at any unit.

| Depth | Reviewers | Model when `review.model` is `auto` | Rounds |
| --- | --- | --- | --- |
| Quick | 1 | the cheapest | Review 1; Review 2 only if Review 1 is Blocking |
| Standard | 1 | the cheapest capable, at a higher effort | up to Review 2 |
| Deep | 3, in parallel, none shown another's report until all have written theirs | the cheapest capable; the `security` tier's stronger model when a security trigger fires | up to Review 3 |

`review.rounds` lowers a depth's round budget, never raises it. Use the user's reviewer model when set (`review.model`), naming it with `delegate open --agent`. Otherwise the user's routing table names the model and effort: open each reviewer with `delegate open --kind review`, which takes the table's review row, and in the `security` tier, which a security trigger or a rule's `tier` sets, add `--tier security`, which takes its security-tier row: a stronger model whatever the depth, in the default table the coordinator's own at `high`, after the user's yes. Where the routing table and the depth's model above differ, the routing table wins. The estimated cost names the reviewer model and roughly what one review of a change this size costs on it, times the reviewers; where past reviews were delegated and measured, Track Work's `working-record.mjs estimate --plan` shows what they cost by model and effort (kind `review`). The plan names the humans the policy asks to approve; say so in the Return report, since nothing enforces it.

When the task has a Working Record, record the plan as one `Review gate` Material update through [Track Work](../../skills/track-work/SKILL.md), in the shape its [format reference](../../skills/track-work/references/working-record-format.md) defines. Without a record, state the same in the Return report. Until Freeflow's gates enforce it, this gate is your check: nothing in the host stops a delivery without it.

## Perform A Selected Independent Review

Goal: a separate context judges the state from the evidence and reports once.

The reviewer did not produce the reviewed state. Give it, or point it to, the work product or the complete artifact, source truth, dependencies, and evidence needed to judge it directly, never only the producer's summary, reasoning, claimed result, or change description. Brief a reviewer of work with pointers to where its inputs live, not pasted copies, and run [check-brief](scripts/check-brief.mjs) on the brief before dispatching, as Work Review's Independent Review says; [review-packet](scripts/review-packet.mjs) prefills that brief from the task folder, names the gate triggers the diff shows and the round budget, and runs check-brief; brief a reviewer of anything else with Artifact Review's prompt. When the task has a task directory, save the brief as `reviews/R<n>-brief.md` there and the returned report as `R<n>-report.md` beside it, where `<n>` numbers the task's reviews in sequence, whatever their round; review-packet takes the next free number and never replaces a review that has reported. Without a task, review-packet uses this session's `reviews/` folder in the Freeflow home. Delete nothing there without the user's yes. For a Deep review, write one brief per reviewer (`--reviewer a`, `b` and `c`: `R<n>a-brief.md` and so on), dispatch the three in one message, each in its own copy, and read none of their reports until all three have returned; a reviewer that does not return leaves the review Inconclusive until it does or you stop it, with the reason in the adjudication. Start and run the reviewer as Execute Work's [delegation](../execute-work/references/delegation.md) reference says; its brief and report stay as this section describes.

Use supplied and available evidence; a covered active check uses Verify Work's check-result and claim-result semantics without changing review ownership.

The independent judgment is:

- **Blocking:** at least one Blocking Issue.
- **Inconclusive:** no Blocking Issue, but a material Question or Needs evidence prevents judgment.
- **Non-blocking:** only Non-blocking Issues remain.
- **Pass:** no Issues or material unresolved items remain.

Improvements and Pre-existing items do not change the judgment or authorize implementation or revision. Every judgment ends the review.

## Bound Independent Review

Goal: independent judgment is spent where it changes the outcome.

For the same reviewed state and boundary or intended use:

The plan's depth sets the budget for its change, as the table in The Review Gate says: Review 3 only for a Deep review.

- **Review 1:** first selected independent review, broad by default.
- **Review 2:** separately selected focused follow-up when corrections or revisions, affected interactions or dependencies, new evidence, or remaining risk still require independent judgment.
- **Review 3:** exceptional, separately authorized, and final; only after the cause, revision basis, and correction or dependency boundary are understood.

A fix or revision does not automatically require another review. Corrections that change what a check accepts or refuses justify a focused Review 2 on the correction diff, even after a Non-blocking Review 1. If Review 2 remains Blocking, adjudicate it before acting again; then diagnose a repeated, extending, invalidating, or unclear cause, and return an unrelated clear local defect to its owner when diagnosis would add no information, rather than fix and dispatch Review 3 automatically. If Review 3 remains Blocking, rethink the approach rather than correct it again: route the blocker to diagnose, or to Discuss Work when the approach itself is in question. Start a new cycle only for a materially new reviewed state and boundary or intended use. Self-review does not consume this budget.

## Stop At The Selected Result

Independent review ends with its report. Adjudication ends with dispositions and an explicit next route. Do not turn optional improvement into unfinished work; preserve the agreed user-facing return boundary and any unresolved limits.