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

Red Flags - STOP

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