---
name: nemoclaw-maintainer-pr-comparator
description: "Compare competing NemoClaw PRs for one issue and recommend a merge or salvage candidate from review evidence."
user_invocable: true
---

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
<!-- SPDX-License-Identifier: Apache-2.0 -->

# PR Comparator

Compare PRs for one issue. Tier 0 determines eligibility. Tiers 1 and 2 score correctness and quality.
Tier 3 resolves ties. If no PR passes Tier 0, rank eligible PRs for salvage.

## Prerequisites

- `gh` CLI installed and authenticated
- A target repository with an issue that has two or more open PRs

## Repo policy

The defaults use NemoClaw conventions for CODEOWNERS, DCO, CodeRabbit, and `docs/`.
Read the canonical superseded-PR attribution policy in
`../nemoclaw-maintainer-policies/references/workflow-policy.md`.
Edit `repo-policy.md` for another repository.

Execute comparator helpers from a fetched canonical NVIDIA/NemoClaw `main` checkout, or verify
their executable code and dependencies against that revision before use. Candidate-modified helpers
must not receive GitHub credentials. Inspect helper source when needed; a section heading does not
establish trust.

## Workflow

### Step 1: Parse issue

Read the issue body and all comments. Extract each acceptance criterion:

```bash
gh issue view <issue-number> --json title,body,comments
```

Comments can add requirements that are absent from the issue body.

### Step 2: Discover candidate PRs

```bash
scripts/find-candidates.sh <issue-number>
```

Applies a single default order with stop conditions.

### Step 3: Detect supersession and transferred work

```bash
scripts/parse-supersession.sh <pr-number-1> <pr-number-2> ...
```

Parse the case-insensitive statement families implemented by `scripts/parse-supersession.sh`:

- `supersed[a-z]*` before `#N`: `supersedes #N` points from the current PR to `#N`; `superseded by #N` points from `#N` to the current PR.
- `replac[a-z]*` before `#N`: `replaces #N` points from the current PR to `#N`; `replaced by #N` points from `#N` to the current PR.
- `clos[a-z]* in favor of` before `#N`: `closes in favor of #N` and `closed in favor of #N` point from `#N` to the current PR.
- `fold[a-z]* in` before `#N`: `folds in #N` points from the current PR to `#N`; `folded into #N` points from `#N` to the current PR.

The bracket expressions describe the parser grammar; they are not literal PR body text.
A `follow-up to #N` statement is a related-PR signal, not a supersession declaration, unless one of these phrases also appears.
These statements record a relationship.
They do not rank a candidate or prove that its diff contains another contributor's work.

For each declared or suspected replacement, compare the commits and diffs and classify the relationship:

- `independent`: The PR implements the issue without carrying material code, tests, or documentation from another contributor.
- `transferred`: The PR carries material work from another contributor.
- `unclear`: The available evidence does not establish whether another contributor's work remains.

For `transferred`, apply the canonical superseded-PR attribution policy before setting a winner or recommending that the source PR be closed.
For `unclear`, leave `winner` null and request maintainer judgment.

### Step 4: Tier 0 gates

```bash
scripts/collect-gates.sh <pr-number>
scripts/check-coderabbit-threads.sh <pr-number>
git fetch --no-tags origin refs/heads/main:refs/remotes/origin/main
bash <(git show origin/main:.agents/skills/nemoclaw-maintainer-day/scripts/run-trusted-check-gates.sh) <pr-number>
```

All six gates are required.
Gate 3 accepts `BEHIND`, but fails closed on transient `UNSTABLE` evidence and on `BLOCKED` because
the comparator cannot prove a stable merge result or every GitHub branch-protection condition.
Separately confirm whether an active rule requires an up-to-date branch. If so, integrate the base
and rerun all candidate evidence before declaring the PR eligible to merge.
Treat PR Review Advisor output as input for maintainer review. Do not treat it as merge authorization.
See `checks/tier-0-gates.md`.

### Step 5: Tier 1 correctness

Apply the six model checks in `checks/tier-1-correctness.md`.

### Step 6: Tier 2 quality

Apply the four model checks in `checks/tier-2-quality.md`.

### Step 7: Weighted score

- Build the Tier 0 eligibility set from these Boolean keys: `state_open`, `ci_green_sha`, `mergeable`, `contributor_compliance`, `branch_protection`, and `coderabbit_threads_resolved`.
- Stop if a candidate omits a required key, has an unknown key, or has a value that is not Boolean.
- Only PRs for which all six gates are `true` enter happy-path scoring.
- Each pass = full points
- Each yellow = half points
- Each fail = zero
- Tier 1 weight: 2.0× per check
- Tier 2 weight: 1.0× per check

### Step 8: Tier 3 ranking

Compute the mode from the Tier 0 results. Do not accept a mode from the caller.
In happy mode, set `winner` only to an eligible PR and set `closest_to_ready` to null.
Leave `winner` null when the evidence does not support a merge recommendation.
Do not set `winner` for a replacement with transferred work until the required attribution is present and verified.
In degraded mode, set `winner` to null.
Set `closest_to_ready` only to an open PR that passes contributor requirements.
See `tiebreakers.md`.

### Step 9: Emit verdict

Use `templates/verdict.md` and render the result with `scripts/render-verdict.py`.
Stop if the renderer exits with a nonzero status. Do not recommend a merge.
The renderer validates the gate schema, mode, winner eligibility, and salvage-candidate eligibility.
The reviewer remains responsible for the score, ranking, and evidence.
For each judgment, include evidence, the inference, and the score.

## Reference files

- [repo-policy.md](repo-policy.md) — Repository settings.
- [checks/tier-0-gates.md](checks/tier-0-gates.md) — Six eligibility gates.
- [checks/tier-1-correctness.md](checks/tier-1-correctness.md) — Six correctness checks.
- [checks/tier-2-quality.md](checks/tier-2-quality.md) — Four quality checks.
- [tiebreakers.md](tiebreakers.md) — Tier 3 ranking and degraded mode.
- [templates/verdict.md](templates/verdict.md) — Output template.
- [validation/backtest.md](validation/backtest.md) — Historical test cases for the skill.

## Scripts

- `scripts/find-candidates.sh` — PR discovery
- `scripts/collect-gates.sh` — Tier 0 gate evaluation
- `scripts/check-coderabbit-threads.sh` — GraphQL thread-resolution check
- `scripts/parse-supersession.sh` — body parsing for supersession refs
- `scripts/render-verdict.py` — verdict scorecard renderer

## Limits

Run `nemoclaw-maintainer-cross-issue-sweep` separately when you need related-issue evidence.

This skill does not:

- run PR code against adversarial inputs
- scan other issues for related behavior
- simulate reverts against related PRs
- run static analyzers such as CodeQL or Semgrep