Embed

---
name: human-pickup-review
description: Pick up a PM ticket flagged with [human:ready-for-review] and run a peer review on each linked engineering ticket (or on the PM ticket itself when none is linked)
argument-hint: <pm-ticket-key>
---

You are picking up a code review handoff. The engineer (human or AI) who finished the work posted a structured comment on a PM ticket with the format:

```
[human:ready-for-review]
engineering: <ENG_KEY_1>, <ENG_KEY_2>
branch: main
commits: 2037e40, 64bb370
```

The `engineering:` line is present only in split topology (separate engineering tracker). In single-tracker topology it is absent — the review target is the PM ticket the comment sits on.

Your job: read that handoff, run the `human-reviewer` agent against each review key (each engineering key, or the PM key itself when the `engineering:` line is absent), then post a follow-up comment on the PM ticket summarising the outcome.

## Steps

1. **Resolve the PM ticket.** `$ARGUMENTS` is the PM ticket key (e.g. `<PM_KEY>`). `human get <PM_KEY>` must succeed — the CLI auto-detects the owning tracker from the key shape; there is no tracker to pick by hand.

2. **Read the handoff.** Run `human handoff show <PM_KEY>` — it returns the newest `[human:ready-for-review]` handoff parsed as JSON:
   - `engineering` — the engineering ticket keys. May be absent (single-tracker topology): the review keys are then just `<PM_KEY>` itself.
   - `branch` — the branch the reviewer should be on.
   - `commits` — short SHAs, for cross-checking.

   If the command reports no handoff, stop and report: `No ready-for-review handoff on <PM_KEY>`. Do not guess.

   Do NOT proceed against a branch that disagrees with `branch`. The reviewer's Step 0 binding gate checks out the handoff branch itself and returns `unreviewable` on any mismatch — never review "the current branch as-is" hoping it is close enough, and never post a verdict for code that is not the handed-off branch.

3. **Run the reviewer per review key, bound to the handoff.** For each key in `engineering` (or for `<PM_KEY>` when it is absent), invoke the existing reviewer agent via the Task tool, threading the handoff's `branch`/`commits` as the binding so the agent verifies the checkout before reviewing:
   ```
   Task(subagent_type="human-reviewer", model="opus", prompt="Review changes for ticket <REVIEW_KEY> --branch=<branch> --commits=<commits>")
   ```
   Each run writes `.human/reviews/<review_key_lowercased>.md`. Review ONLY the keys named in this handoff, and post markers ONLY on `<PM_KEY>` — never on any ticket the handoff does not name.

4. **Collect verdicts.** Open each `.human/reviews/<key>.md` the reviewer produced. The first line under `## Summary` is the outcome (`pass`, `pass with notes`, `fail`, `incomplete`, `unreviewable: <reason>`, or `decision-required: <one-line fork>`). The last two are not verdicts — they are escapes, handled below BEFORE any roll-up.

   If ANY reviewed key's Summary starts with `unreviewable`, the reviewer could not obtain that code — skip the roll-up entirely and go to the unreviewable branch of step 5. Otherwise, if ANY reviewed key's Summary starts with `decision-required`, the review reached no verdict for that key because the ticket itself admits a genuine product/scope fork — skip the roll-up entirely and go to the decision-required branch of step 5. Otherwise roll them up into an overall verdict:
   - any fail → `fail`
   - else any incomplete → `incomplete` (a ticket acceptance criterion is unmet — blocks deploy and loops the work back to be built, exactly like a fail)
   - else any pass-with-notes → `pass with notes`
   - else → `pass`

   A `fail` or `incomplete` overall verdict blocks the deploy and the board re-runs the build against the review findings — no follow-up action is needed here beyond posting the `[human:review-complete]` comment.

5. **Post the follow-up comment on the PM ticket.**

   **Unreviewable escape (leading branch).** If any reviewed key was `unreviewable`, do NOT post `[human:review-complete]` and do NOT dispatch any rework — nothing was reviewed, so a verdict would be a lie. Post `[human:review-failed]` instead, naming the unreachable ref(s) per affected key so the board renders an honest, retryable stage failure:
   ```bash
   human marker post <PM_KEY> review-failed --field reason="<REVIEW_KEY>: <reachability reason — e.g. handoff branch feat/x not found — no code was reviewed>"
   ```
   With several affected keys, pass one `reason` value with embedded newlines — one `<REVIEW_KEY>: <reason>` line each; continuation lines are indented automatically. Tell the user how to make the code reachable (push the branch / commit with the ticket key), and STOP — do not run the pass/notes/fail posting below.

   **Decision-required escape.** If any reviewed key was `decision-required` (and none was `unreviewable`), do NOT post `[human:review-complete]` — there is no verdict to roll up, only a choice for a person. Post the fork as an options block on the PM ticket instead, so the board can render the choices and relaunch the picked one:
   ```bash
   human marker post <PM_KEY> options \
     --field stage=implementation \
     --field context="<REVIEW_KEY>: <the decision-required one-liner>" \
     --field 1="<first option, one line>" \
     --field 2="<second option, one line>"
   ```
   With several affected keys, name the first fork found in `context` and mention the rest in a review key prefix per line, same as the unreviewable branch above. Then STOP — do not run the pass/notes/fail posting below.
 The comment is the canonical record of the review — it must carry the reviewer's full findings inline so a reader (and the board detail panel) sees what was found without opening any local file. The `.human/reviews/<key>.md` files remain as working artifacts, not the source of truth. `commits:` is the handoff's own commit list (step 2's `commits`), so the verdict records which round it judged — a later handoff naming nothing beyond it is not a new round. Post it with:
   ```bash
   human marker post <PM_KEY> review-complete \
     --field verdict="<overall-verdict>" \
     --field commits="<the handoff's commits: from step 2, comma-separated>" \
     --field reviews="<REVIEW_KEY_1>: <verdict> — .human/reviews/<review_key_1>.md\n<REVIEW_KEY_2>: <verdict> — .human/reviews/<review_key_2>.md" \
     --body-file - <<'FINDINGS_EOF'
   ## Findings
   <the full findings for each reviewed key, inlined from the reviewer's output:
    what was checked, every issue found (or "no issues"), and any notes — the
    substance of each .human/reviews/<key>.md, not just a pointer to it>
   FINDINGS_EOF
   ```
   The rendered `[human:review-complete]` header mirrors the handoff header so future tooling can close the loop (e.g. auto-transition the reviewed tickets to Done when all reviews pass), and the inlined `## Findings` section makes the on-ticket comment the complete review record.

6. **Report to the user.** Summarise in plain text: which tickets were reviewed, the overall verdict, and where each review lives.

## Principles

- **Do not invoke `human-reviewer` on keys outside the handoff block.** Only review what the handoff claims. Scope creep in the review defeats the purpose of the convention.
- **Do not transition ticket status.** Closing/rejecting is the user's decision after reading the review. This skill reports, it does not decide.
- **Do NOT use `AskUserQuestion`.** Execute autonomously. If the handoff is missing or malformed, stop and report.