review-skills

Two models argue over a pull request before anything is posted. You keep the merge.

debate-review has a main reviewer read the PR, a second reviewer try to knock its findings down, and the main reviewer make the final call. One review with inline comments lands on the PR, posted from your own gh, glab, or az account. babysit-pr then works the rounds: verifies each finding, fixes the blockers, replies in-thread, resolves, and re-triggers the next review. Both skills run through whatever coding agent you already drive (Claude Code, Codex, Cursor, OpenCode, Grok, and others) and the model subscriptions you already pay for.

npx skills add amElnagdy/review-skills

Then ask your agent:

Use $debate-review on https://github.com/owner/repo/pull/123
Use $debate-review --local on this repo before I open a PR.
Use $babysit-pr on PR 123 until it is ready to merge.

flowchart LR
  P["PR or MR"] --> M["Main reviewer<br/>lane review-main"]
  M -->|"findings"| D["Debate reviewer<br/>lane review-debate"]
  D -->|"confirm / refute / downgrade / add"| F["Main reviewer<br/>final call"]
  F --> R["One review<br/>inline P0 / P1 / P2"]
  R --> B["$babysit-pr<br/>verify, fix, reply, resolve"]
  B -->|"push, re-run"| M

The skills

Requirements

• Node 18 or newer.

• Git 2.31 or newer for Azure DevOps (--config-env keeps the access token out of command arguments).

• gh (GitHub), glab (GitLab, including self-hosted) or az (Azure DevOps) logged in to an account that can comment on the PR. Reviews and replies post as that account. Azure DevOps needs no az extension: the script uses az rest against the REST API.

• delegate-skills, which dispatches the reviewer models through the *-delegate relays, read-only.

• Two delegate lanes named review-main and review-debate. Create them once with $delegate-setup:

  Use $delegate-setup to add two lanes: review-main on claude at high effort and review-debate on codex at high effort.
  

  Pick two different implementers. The debate is only worth something when the second model does not share the first one's blind spots. Keep these lanes for the reviewer; if you already use a debate lane for plan debates, leave it alone. Only implementers whose relay supports --read-only are accepted, so the reviewers cannot touch your tree.

What a review looks like

Each finding is one inline comment, anchored to the lines it is about, rendered as a forge alert so the colour reads before the words:

The review body carries a level count table, who reviewed, and a short summary. Each comment and the body start with an HTML marker (<!-- debate-review ... -->) that babysit-pr uses to recognise the threads, since they are posted from your account rather than a bot's. One review per head sha: a re-run on the same push exits with code 3 instead of posting again. Templates and the marker format are in comment-format.md; the JSON contract between the three passes is in schema.md.

The reviewers are prompted for precision, not volume: blocking bugs with a concrete trigger and wrong result, spec and standards violations quoted against the rule, and little else. The second reviewer can only refute a finding when it can point at the code that makes it impossible. Findings below the confidence floor are dropped before anything is posted.

GitHub, GitLab and Azure DevOps

Azure DevOps has no single review object, so one debate-review is N inline threads plus one closed summary thread carrying the marker. --force and the "already reviewed" check read the same marker back off the PR's threads, so a re-run on an unchanged head still exits 3.

Local preview

--local reviews the files on disk (committed, uncommitted, and untracked, honoring .gitignore) against a base branch. It never calls a forge CLI. --dry-run still needs a live PR; it only skips the post. The two flags do not combine. Local snapshots reject non-UTF-8 Git paths instead of silently changing their bytes.

Run it by hand

Your agent normally runs these for you. They are here for testing, CI, or when there is no agent in the loop. <skill-dir> is the directory containing the skill's SKILL.md.

node "<skill-dir>/scripts/review-pr.mjs" --local                  # working tree; print, no forge
node "<skill-dir>/scripts/review-pr.mjs" <pr-url | number> --dry-run   # print, do not post
node "<skill-dir>/scripts/review-pr.mjs" <pr-url | number>             # post
"<babysit-skill-dir>/scripts/threads.sh" <number>                      # harvest one round as JSON

review-pr.mjs --help lists the flags: --local to review the working tree with no forge, --main / --debate to override the lanes for one run, --contested post|drop, --min-confidence, --timeout (default 30 minutes per reviewer), --force to post again on the same head, --keep to leave the temporary worktree or snapshot clone. Every run leaves its briefs, raw model output, and the three JSON documents under ~/.cache/debate-review/<owner>__<repo>/<N>/<head>/ so a surprising review can be traced back to the pass that produced it.

How this relates to the sibling repos

• delegate-skills is the transport. review-pr.mjs reads your lanes and calls the matching relay; this repo has no model code of its own.
• guard-skills are review lenses for code an agent just wrote. The reviewers here cannot load them (the relays run the reviewer with skills disabled, on purpose), and they are tuned for a different job than Clean Code checks. Where a guard fits is the babysitter's own fixes: babysit-pr runs the matching guard on a fix before pushing it, when one is installed.

Development

node --test test/*.test.mjs

The babysit tests run threads.sh end to end against fake gh and glab binaries in test/fixtures/babysit/. The debate-review tests drive the Azure forge functions against a fake az in test/fixtures/azure/. Both suites run without network.

License

MIT