---

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:

CopyGH_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

Red Flags - STOP

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