# pm_review
{{< badge content="Vanguard" color="blue" class="tier-badge" >}} {{< badge content="Some actions: Sovereign" color="purple" class="tier-badge" >}}

The `pm_review` tool orchestrates task review workflows. Reviews are how completed work gets evaluated before it ships — you start a review on a task, assign reviewer agents, launch them against the work, publish findings, and optionally record lightweight review scores. Auditor workflows and audit score runs live in [`pm_audit`](../audits/).

## Actions

`start`, `list`, `delete`, `update_assignment`, `comment`, `comment_list`, `comment_delete`, `verify_ready`, `publish`, `get_prompt`, `launch_reviewer`, `statuses`, `score_record`, `score_list`, `help`

### Sovereign-only actions

The following actions require the **Sovereign** tier — they are not available at Vanguard:

- `launch_reviewer` — launches an agent session

---

## start

Start a review for a task.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `reviewerHandle` | string | Conditional | Single reviewer handle (preferred). Required if `reviewerHandles` is omitted. |
| `reviewerHandles` | string[] | Conditional | Multi-reviewer alternative. Required if `reviewerHandle` is omitted. |
| `requestedByHandle` | string | No | Who requested the review (defaults to actor) |
| `summary` | string | No | What's being reviewed |
| `actorHandle` | string | Yes | Actor handle |

### Example

```text
pm_review {
  action: "start",
  taskKey: "MYAPI-42",
  reviewerHandle: "sigrid",
  actorHandle: "@alice",
  requestedByHandle: "alice",
  summary: "Rate limiting implementation ready for review"
}
```

---

## list

List reviews for a task.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `reviewerHandle` | string | No |
| `status` | string | No |

---

## delete

Delete a review.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `reviewId` | string | Yes |
| `actorHandle` | string | No |

---

## update_assignment

Update reviewer assignment status.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `reviewId` | string | Yes |
| `assignmentId` | string | Yes |
| `status` | string | Yes |
| `feedback` | string | No |
| `actorHandle` | string | No |

---

## comment / comment_list / comment_delete

Manage review comments. Comments can be threaded via `parentCommentId`.

### comment

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `body` | string | Yes | |
| `reviewId` | string | No | |
| `assignmentId` | string | No | |
| `parentCommentId` | string | No | For threaded replies |
| `actorHandle` | string | No | |

### comment_list

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `reviewId` | string | No |
| `assignmentId` | string | No |

### comment_delete

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `commentId` | string | Yes |
| `actorHandle` | string | No |

---

## verify_ready

Check if a task can transition to `verified`. The current implementation verifies that all task reviews have reached an approved status; it does not independently inspect score records.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |

---

## publish

Publish a review — combines comment, status, and score in one operation.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `body` | string | Yes | Review comment body |
| `scoredHandle` | string | Yes | Handle of agent being scored |
| `score` | number | Yes | Score 0–100 |
| `reviewId` | string | No | Review to publish to (auto-detected if omitted) |
| `assignmentId` | string | No | Requires `reviewId` |
| `status` | string | No | Desired status (inferred from body/recommendation) |
| `recommendation` | string | No | `ready`, `reject`, or `changes_requested` |
| `feedback` | string | No | Additional feedback text |
| `notes` | string | No | Notes for the score |
| `actorHandle` | string | No | |

### Example

```text
pm_review {
  action: "publish",
  taskKey: "MYAPI-42",
  body: "Implementation looks clean. Tests cover edge cases well.",
  scoredHandle: "claude-coder",
  score: 92,
  recommendation: "ready"
}
```

---

## get_prompt

Fetch review prompts for a reviewer.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `reviewerHandle` | string | Conditional | Required if multiple reviewers |

---

## launch_reviewer

Launch a reviewer agent session attached to an existing worktree.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `clientRequestId` | string | Yes | Idempotency key |
| `actor` | string | Yes | Actor string (e.g., `"@pm"`) |
| `taskKey` | string | Yes | |
| `sourceSessionUlid` | string | Yes | Session whose worktree is being reviewed |
| `agentId` / `agentHandle` | string | No | Specific reviewer |
| `provider` | string | No | Provider override |
| `launcherConfigKey` | string | No | Preset override |
| `prompt` | string | No | Initial user message override (skill mode) |
| `systemPrompt` | string | No | System prompt override |
| `config` | object | No | Launcher config overrides |
| `role` | string | No | Role (default `reviewer`) |
| `capabilityKeys` | string[] | No | |
| `additionalInstructions` | string | No | |
| `maxRuntimeSeconds` | number | No | |
| `run` | boolean | No | Run immediately (default `true`) |

### Example

```text
pm_review {
  action: "launch_reviewer",
  clientRequestId: "01HXYZ...",
  actor: "@skadi",
  taskKey: "MYAPI-42",
  sourceSessionUlid: "01HABC...",
  agentHandle: "sigrid",
  launcherConfigKey: "reviewer-claude"
}
```

---

## statuses

List available review statuses. Takes no parameters.

```text
pm_review { action: "statuses" }
```

---

## score_record

Record a lightweight review score that stays attached to the task review record. This is different from audit score runs in `pm_audit`.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `scoredHandle` | string | Yes |
| `score` | number | Yes |
| `reviewId` | string | No |
| `assignmentId` | string | No |
| `notes` | string | No |
| `actorHandle` | string | No |

---

## score_list

List lightweight review scores for a task.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `reviewId` | string | No |
| `assignmentId` | string | No |

---

## help

```text
pm_review { action: "help" }
```

## Related

- [Reviewable AI Agent Workflows](/valdr/docs/features/reviewable-workflows/) — product-level overview of evidence-backed review, audit, and approval gates
- [pm_audit](../audits/) — dedicated auditor launch, evidence, and audit score-run surface
- [pm_session](../sessions/) — underlying session mechanics
- [pm_task](../tasks/) — reviews are attached to tasks