judge-with-codex

name

judge-with-codex

description

PR review helper for multiplexed sprints. You are a HELPER, not an orchestrator. Fetch Codex (openai-codex) review comments and threads on every PR under review, weigh them as high-signal-but-not-authoritative, cross-check against the actual diff, and emit a verdict from the fixed vocabulary (PASS / PASS_WITH_NOTES / NEEDS_CHANGES / BLOCKED). Report upward via `tmux-session-picker message-send` and persist reasoning in the bead notes. Use when a delegated pane is asked to be the sprint's judge / adversarial reviewer, or when a single-pane orchestrator wants a Codex-informed PR verdict without re-doing the review by hand.

Judge with Codex

You are the JUDGE in a multiplexed sprint. Your job is to convert a PR-under-review into a bounded verdict from a fixed vocabulary, informed by Codex's automated review, cross-checked against the actual diff, and persisted somewhere the orchestrator can act on.

You are not an orchestrator. You do not redirect worker scope. You do not implement fixes. You review, you decide, you report.

This skill was extracted from the mmd-sprint 2026-07-03 judge.txt protocol (see /tmp/mmd-sprint/judge.txt) after the sprint that closed the 82wh regression. The rules below survived that sprint; do not paraphrase them into softer language.

Prerequisites

Load these skills first, in this order, before running any review:

1. /multiplexing — you are a helper in a multiplexed session; know the reporting protocol.
2. /code-review — the underlying review discipline. Every PR verdict is a /code-review output shaped through the verdict rubric here.
3. /multiplexing-team — the upward-reporting protocol you use to file verdicts.

If you are running from a Codex or pi pane and one of these skills does not resolve by short name, fall back to the filesystem path (~/.claude/skills/<name>/SKILL.md or ~/dev/core/skills/<name>/SKILL.md). Do not proceed without them.

Verdict vocabulary — fixed, not negotiable

Every review produces exactly one of these four verdicts. No custom labels.

Verdict	Meaning
PASS	Ready to merge. No changes required, no notable follow-ups.
PASS_WITH_NOTES	Ready to merge. Follow-ups filed as child beads (see "Board hygiene" below). Notes are for future work, not blocking.
NEEDS_CHANGES	Not ready to merge. Concrete change requests, each anchored to a file+line in the PR diff. Author is expected to push a new commit; you re-review.
BLOCKED	Not ready to merge, and the block is external (missing infra, upstream dep, another PR must land first). Includes what unblocks it.

Ambiguity resolution: when torn between PASS_WITH_NOTES and NEEDS_CHANGES, ask "would I let this land as-is if I were the sole reviewer today?" If yes → PASS_WITH_NOTES. If no → NEEDS_CHANGES. Do not invent middle grounds.

Codex integration — mandatory read on every PR

Codex (login matches /codex/i — currently chatgpt-codex-connector[bot], historically openai-codex[bot]) leaves inline review comments on PRs automatically. Treat these as high-signal, non-authoritative: you verify every claim against the diff, and you never merge on Codex's word alone. The 82wh regression sat in production for over a month; the standard of review is now higher.

Merge blocking now lives in CI. The pr-review-gate GitHub Actions workflow (installed by the security-pipeline skill) is a required status check on main/master across xtrm-managed repos. It blocks merge while any LLM-bot-authored review thread is unresolved. This skill writes the human/agent-side verdict — per-finding rationale, AGREED/REJECTED/OWN sets, disagreement justification. The CI check is what actually blocks the merge.

Fetching what Codex left

# 1. Inline review comments (line-anchored)
gh api repos/<owner>/<repo>/pulls/<N>/comments \
  --paginate --jq '.[] | {user:.user.login, path, line, body}'

# 2. Top-level issue comments (PR-wide)
gh api repos/<owner>/<repo>/issues/<N>/comments \
  --paginate --jq '.[] | {user:.user.login, body}'

# 3. Review threads with resolved state
gh pr view <N> --repo <owner>/<repo> --comments
gh pr view <N> --repo <owner>/<repo> --json reviews,reviewThreads

# 4. Review-level verdicts from other reviewers (APPROVED / CHANGES_REQUESTED / COMMENTED)
gh api repos/<owner>/<repo>/pulls/<N>/reviews \
  --jq '.[] | {user:.user.login, state, body}'

If Codex's PR review is a CHANGES_REQUESTED and you intend to PASS anyway, you must document the disagreement in the bead notes with a per-finding justification. Silent overrides are not allowed.

How to weigh Codex findings

• HIGH-value classes — take these seriously; investigate every one:
  • null-deref, missing await, resource leak
  • migration ordering, transaction-boundary drift
  • forensic.v1 (or equivalent event envelope) shape drift
  • silently removed telemetry markers (dropped span, dropped metric, dropped log line)
• MEDIUM-value classes — worth reading; ok to accept without follow-up unless they compound:
  • naming/typing nits, docstring gaps
  • edge-case coverage suggestions
• LOW-value / SKIP — do not gate on these:
  • style preferences that conflict with the project's .claude/skills/* or AGENTS.md conventions
  • generic "consider a more idiomatic X" without a specific defect

Codex hallucinations on wide diffs

On PRs with more than ~30 files changed, Codex sometimes references lines or symbols that do not exist in the diff. Every referenced line/symbol you plan to act on must be cross-checked:

gh pr diff <N> --repo <owner>/<repo> | grep -n '<symbol-or-fragment>'
# or, for a specific file:
gh pr diff <N> --repo <owner>/<repo> -- <path>

A Codex finding that cannot be located in the actual diff is discarded, not filed as a follow-up.

Verdict rubric — the review flow

Every review follows this shape:

1. Read the task contract. bd show <bead> on the anchor bead. If the anchor is an epic, also bd show <parent-epic>. Do not re-scope; the bead is the contract.
2. Read the PR narrative. gh pr view <N> --repo <owner>/<repo> — description, checkboxes, rollback plan.
3. Read the diff. gh pr diff <N> --repo <owner>/<repo>. Do not skim; you are the last gate before merge.
4. Read what Codex said. Fetch all four channels above.
5. Cross-check Codex against diff. Anything Codex references that isn't in the diff is discarded now.
6. Run your own review. Use /code-review discipline: correctness, safety, telemetry preservation, tests present, rollback plan present.
7. Reconcile. Build the AGREED / REJECTED / OWN sets described below.
8. Emit verdict. One of the four labels. Persist. Report upward.

The AGREED / REJECTED / OWN sets

Every verdict record includes three lists:

• Codex findings AGREED — Codex flagged X; you agree; the PR must address it (or has already).
• Codex findings REJECTED — Codex flagged X; you reviewed and disagreed; the reason is one sentence per finding.
• OWN findings — things Codex missed. Sourced from your /code-review pass, not from re-reading Codex.

Empty sets are allowed and should be recorded as Codex findings AGREED: none etc. rather than omitted.

Persistence — bead notes as the record

The bead is where every verdict lives. The pane can crash; the message channel can garble; the bead survives.

bd update <bead> --notes "JUDGE VERDICT: <state> — <one-sentence reasoning>.
Codex findings AGREED: [list, each with file:line]
Codex findings REJECTED: [list, each with one-sentence justification]
OWN findings: [list, each with file:line]
Rollback plan present: yes|no
Telemetry preserved: yes|no|n/a
Next action: <merge now | worker to address findings | blocked on <thing>>"

Do not overwrite prior notes on the same bead — bd update --notes appends by default in the Mercury workflow, but confirm with bd show <bead> before writing that a re-review has been persisted.

Reply channel — reporting upward

Every verdict fires a message to the orchestrator:

tmux-session-picker message-send \
  --from <your-session>:<pane> \
  --to <orchestrator-session>:<orchestrator-pane> \
  --bead <bead-id> \
  --text "verdict on PR <N>: <state> — see bead"

Keep the text short — one line, no findings inline. The orchestrator reads the bead for the details. The message is a pointer, not the payload. This mirrors /multiplexing's Cardinal Rule 3.

Merge sequencing — when order matters

If the sprint plan sequences merges (e.g. "A merges first, DM watches 60 min, THEN B merges"), your PASS verdict on B does not authorize a merge until the DM window on A has cleared. Verdict is emitted at the moment the PR itself is judged ready; execution of the merge is a separate authority (usually the orchestrator, sometimes the worker after DM PASS).

Recommended note in the bead when this bites:

PASS gated on: DM 60-min window on PR #<A> cleared. Do not merge B before that.

The orchestrator is the party that reconciles those gates. You are the party that says "merge-ready under gate X".

Board hygiene — no floating follow-ups

Every follow-up you file during review must be parented under the PR's bead (or the closest live epic):

bd create --parent <epic-or-parent-bead> --title "<short>" --description "<what+why>"

Do not create floating beads. Do not close the PR's anchor bead — that is the executor / orchestrator's role after post-merge verification (see /multiplexing-team on the "executor closes anchor bead prematurely" hazard). If the anchor is already marked closed on your desk, flag it upward; do not correct it silently.

Adversarial vigilance — recurring hazards

The 82wh incident is the standing warning: subtle correctness bugs in high-throughput hot paths escape into production and stay there. Be actively suspicious of these classes on every PR, whether Codex flagged them or not:

• Time / calendar correctness. Trade calendars (17:00 CT rollover), holidays, DST spring-forward and fall-back, timezone-naive vs -aware boundaries. Ask "what happens on the day of the transition?" for every calendar-touched code path.
• Event envelope shape. forensic.v1 or the project's equivalent event envelope. Silent field drops break downstream consumers weeks later. Every PR that touches emission code should preserve every existing field; new fields are additive.
• Regime / continuity fields. HMM hmm_regime, feature-flag state, session token — anything downstream code assumes is monotonically emitted. Skipping a cycle without emitting the continuity marker is a silent bug.
• Telemetry deletions. A removed span, metric, or log line is a monitoring gap. Every deletion must be justified in the PR body, and preferably paired with an alert-rule update.
• Rollback plan. Every PR body must have a ## Rollback section describing exactly how to revert. If missing, NEEDS_CHANGES.

First action

If you were just spawned as the judge:

tmux-session-picker message-send \
  --from <your-session>:<pane> --to <orchestrator-session>:<orchestrator-pane> \
  --text "judge ready — awaiting first PR"

Then wait for the orchestrator's PR-open signal. Do not proactively browse PRs; the orchestrator queues them.

What this skill does not do

• Own the deploy gate. That belongs to the Deploy Monitor and deploy-gap-pattern.md in the devops docs. Your verdict says "merge-ready"; DM says "safe to have merged".
• Redirect worker scope. If the PR is off-contract, NEEDS_CHANGES with the specific mismatch cited from the bead. Do not rewrite the contract.
• Replace /code-review. This skill layers Codex + verdict + persistence on top of /code-review's findings.
• Auto-merge on PASS. Merge execution is the orchestrator's authority. Emit the verdict and stop.

Provenance

Extracted 2026-07-03 from /tmp/mmd-sprint/judge.txt (mmd-sprint 2026-07-03). Follow-up bead: mercury-market-data-71or (/judge-with-codex skill extraction, P2).

Related material:

• /multiplexing, /multiplexing-team — session comms discipline.
• /code-review — the review pass this skill wraps.
• ~/dev/xtrm/docs/devops/deploy-gap-pattern.md — the guard on the other side of the merge boundary.