# Human-agent review loop

Product view:
[revision-anchored review and resolution](https://handover.sh/screenshots/demo-review-and-revisions.png)

Use this workflow when a person or another agent must review an AI-generated
report, query, plan, code file, or other artifact and the producing agent must
act on the feedback.

This is an artifact review workflow. It does not replace runtime approval for
destructive or consequential tool calls.

## Roles

| Role | Responsibility |
| --- | --- |
| Producer | Publishes the artifact and its evidence as an immutable revision |
| Reviewer | Checks claims, evidence, assumptions, permissions, and acceptance criteria |
| Resolver | Reads open annotations, publishes the correction, and links resolved threads to the new revision |
| Review owner | Confirms the correction and decides whether the work can proceed |

One person or agent may hold more than one role, but every action should use its
own authenticated identity.

## Review lifecycle

```text
publish v1
    |
    v
anchor feedback to revision + artifact + exact selection
    |
    v
mention or assign an authorized collaborator
    |
    v
read current revision + artifact + open annotations
    |
    v
publish v2 with expectedRevisionId
    |
    v
resolve only addressed threads with resolvedRevisionId
    |
    v
human verifies the correction
```

## 1. Publish a reviewable artifact

The producer should include:

- the objective and acceptance criteria;
- the generated artifact in its original format;
- source evidence or queries used to create it;
- known assumptions and unresolved questions;
- one named review owner;
- a change summary that explains why this revision exists.

Do not silently replace a file after review begins. Publish a new immutable
revision.

## 2. Anchor actionable feedback

Read the artifact before creating the annotation. Preserve the exact selected
text and enough surrounding context for another actor to locate the finding.

```json
{
  "tool": "handover.annotate",
  "arguments": {
    "handoverId": "hov_example",
    "body": "The conversion claim needs the source query and date range. Attach the query and recalculate the percentage.",
    "target": {
      "revisionId": "rev_v1",
      "artifactId": "art_report",
      "targetKind": "text",
      "selector": {
        "exact": "Conversion increased by 31%.",
        "prefix": "The experiment summary states: ",
        "suffix": " This result informed the rollout decision.",
        "startLine": 18,
        "endLine": 18
      }
    },
    "mentionPrincipalIds": ["prn_resolver"]
  }
}
```

An actionable annotation names:

1. what is wrong, missing, or uncertain;
2. why it matters;
3. the expected correction or verification step;
4. the evidence or constraint the resolver must use.

A mention only notifies an actor who already has access. It must never grant
access to the handover.

## 3. Read before resolving

The resolver should use this sequence:

```text
handover.get
handover.read_artifact
handover.annotations { status: "open" }
handover.thread
```

Before writing, state:

- the current revision ID;
- the open findings being addressed;
- the evidence that will be added or changed;
- any finding that remains unresolved.

If the current revision changed after the resolver read it, stop and refresh
the review state.

## 4. Publish the correction

Append a new revision with `handover.continue`. Supply the exact current
revision as `expectedRevisionId` so another collaborator's work cannot be
overwritten.

The new revision should:

- replace only files that changed;
- inherit unchanged artifacts;
- attach new source evidence;
- explain the correction in the revision note;
- keep unresolved findings visible.

## 5. Resolve addressed threads

Resolve a finding only after the corrected revision exists.

```json
{
  "tool": "handover.update_comment",
  "arguments": {
    "handoverId": "hov_example",
    "commentId": "cmt_finding",
    "status": "resolved",
    "resolvedRevisionId": "rev_v2"
  }
}
```

Do not resolve a thread merely because work started. The linked revision should
contain the correction a reviewer can verify.

## 6. Verify the closed loop

The review loop passes when:

- the original artifact and finding remain inspectable;
- the corrected artifact is a later immutable revision;
- the producer, reviewer, and resolver actions are attributable;
- every resolved finding links to the revision that addressed it;
- unresolved findings remain open and searchable;
- mentions and assignments did not widen access;
- the review owner can reproduce the evidence behind the correction.

## Feedback is not approval

Use artifact annotations for findings and requested changes. Use the agent
runtime, policy engine, or access layer for approval of destructive or
consequential actions. A safe approval prompt should show the proposed action,
affected resource, relevant evidence, uncertainty, and rollback path without
letting untrusted artifact content impersonate the approval interface.

## Continue with Handover

- Human review guide:
  https://handover.sh/guides/human-review-of-ai-agent-output
- Annotation documentation:
  https://handover.sh/docs/annotations
- Live continuation demo:
  https://handover.sh/demo
- Review Agent Skill:
  https://skills.handover.sh/handover-review