---
name: codex-pr-review-loop
description: "Use when managing Codex review iterations for a PR and you must enforce preflight risk-layer checks and post-merge learning capture."
---

# Codex PR Review Loop

## Overview

Run a 5-minute polling loop for PR review threads, but enforce a preflight Codex Context gate and capture post-merge learning when Codex churn occurs.

## Workflow (Preflight + Loop + Post-Merge)

### Preconditions

1. If the user asks for preflight, run Step -1 before PR submission.
2. If PR already exists, proceed to Step 0.
3. `gh` is authenticated.
4. You are allowed to push/merge as part of this explicit user-requested workflow.

### Step -1: Pre-PR Codex Readiness (only when requested)

- Open `.github/PULL_REQUEST_TEMPLATE.md`.
- If any **Risk Layer Trigger** applies, fill the **Risk Layer Addendum** (rules/invariants, boundary matrix >= 3, evidence).
- Ensure **Codex Context** lists delta, invariants, edge cases, tests, and known gaps.
- Run the minimal regression tests that cover the boundary matrix.
- Stop and ask the user to create the PR if it does not exist yet.

### Step 0: Identify PR

- Prefer current branch PR: `gh pr view --json number`.
- If ambiguous, ask for PR number.

### Step 1: Poll review threads, PR issue comments, and PR body reactions

Run:

```
GH_OWNER=<owner>
GH_REPO=<repo>
PR_NUMBER=<number>

gh api graphql -f owner="$GH_OWNER" -f name="$GH_REPO" -F number=$PR_NUMBER -f query='query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){reactionGroups{content users{totalCount}} reviewThreads(first:100){nodes{isResolved path line originalLine comments(first:50){nodes{author{login} body createdAt reactions(content: THUMBS_UP){totalCount}}}}} comments(first:100){nodes{author{login} body createdAt reactions(content: THUMBS_UP){totalCount}}}}}}}'
```

### Step 2: Wait for updates (repeat until update)

- **Do not proceed** unless review threads, PR issue comments, **or PR body reactions** have **new updates** since the last poll (new comments, new threads, updated timestamps, or reaction count changes).
- If no updates are found, **wait 5 minutes and poll again**. Continue doing this automatically until updates appear.

### Step 3: Decide

- **If any review thread comment OR PR issue comment contains** `Codex Review: Didn't find any major issues` **(exact phrase)** **OR** a thumbs-up signal:
  - thumbs-up signal = comment body includes `👍` or `:+1:` **OR** `reactions(content: THUMBS_UP).totalCount > 0` **OR** PR body `reactionGroups` has `content: THUMBS_UP` with `users.totalCount > 0`
  - You may merge to remote `main`, then pull locally. Proceed to Step 6.
- **Else:** treat updated review thread feedback as actionable. Proceed to Step 4.

### Step 4: Fix bugs or requested changes

- Apply fixes in code.
- Add/adjust tests for regressions.
- Run relevant verification commands.
- Commit changes locally.
- Push to update the PR.

### Step 5: Reply and wait

- Post a **separate PR issue comment** (not a thread reply) with **exactly** `@codex review`.
  - Use: `gh pr comment <PR_NUMBER> --body "@codex review"`
- After replying, immediately return to Step 2 (wait 5 minutes, poll again until updates appear).

### Step 6: Merge and sync

- Merge PR to `main` on remote (e.g., `gh pr merge --merge` or project-required strategy).
- Pull latest `main` locally.

### Step 7: Post-merge learning capture (when Codex churn occurred)

- If the PR required multiple @codex review cycles or post-merge fixes:
  - Run a retrospective using **pr-review-cycle-retro** on this PR.
  - Update `docs/retrospective/` entries if this repo uses them.
  - If a new cause category appears, update the churn skill taxonomy.

## Guardrails

- Do not merge until review thread content, PR issue comments, **or PR body reactions** explicitly include: `Codex Review: Didn't find any major issues` **or** a thumbs-up signal (see Step 3).
- Do not take any action (fix/respond/merge) unless review threads have new updates since the last poll.
- If no updates are found, you MUST keep waiting in 5-minute increments until updates appear.
- Do not request `@codex review` if a Risk Layer Trigger applies but the Addendum is incomplete.
- Always run tests appropriate to the change before pushing.
- Follow repo rules (e.g., no `git push` unless this skill is explicitly requested).
- If merging/pushing requires confirmation in the current environment, ask for explicit confirmation.

## Common Mistakes

- Triggering `@codex review` without filling Risk Layer Addendum when required.
- Treating Codex churn as a tooling issue instead of a stage/contract issue.

## Rationalization Table

| Excuse                                      | Reality                                                   |
| ------------------------------------------- | --------------------------------------------------------- |
| "Preflight is optional"                     | If Risk Layer Trigger applies, the addendum is mandatory. |
| "Codex asked again, so we can skip context" | Missing context amplifies churn.                          |

## Red Flags - STOP

- Risk Layer Trigger checked but Addendum is missing.
- Multiple @codex reviews without any delta summary.