# Codex Pr Review Loop > Use when managing Codex review iterations for a PR and you must enforce preflight risk-layer checks and post-merge learning capture. - Skill: `tomevault-io/codex-pr-review-loop` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/codex-pr-review-loop` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/codex-pr-review-loop/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/codex-pr-review-loop --- # 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= GH_REPO= PR_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 --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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/victorgpt) — claim your Tome and manage your conversions.