Codex Review Churn Analysis (PR Retrospective)
Overview
Explain why Codex Cloud review had to be re-run. Attribute causes to specific development stages, not just PR outcomes.
When to Use
- Multiple @codex review cycles on the same PR.
- The same feedback appears across successive Codex reviews.
- Follow-up fix PRs exist shortly after merge.
- You need stage-level causes (design / implementation / testing / review packaging / release).
When NOT to use:
- Human-review-only churn.
- Pure formatting or mechanical PRs.
Core Pattern
- Select: Find PRs with Codex review churn (comment -> code update -> Codex review).
- Isolate: Filter only Codex Cloud reviews and actionable feedback.
- Evidence: Collect a traceable chain (Codex feedback -> code change or follow-up fix).
- Classify: Assign primary + secondary stage causes.
- Abstract: Roll causes into a stable taxonomy.
- Aggregate: Summarize causes across frontend/backends.
- Prevent: Enforce the PR template risk-layer gate before any future @codex review.
Quick Reference
| Item |
Rule |
| Codex cycle |
Codex review comment -> code update -> new Codex review |
| Evidence |
Codex comment + fix commit OR follow-up fix PR OR regression doc |
| Stage attribution |
design / implementation / testing / review packaging / release |
| Mixed PR |
record both frontend and backend impact |
| Noise guard |
if Codex comments are generic, mark low-signal |
| Risk-layer gate |
if any trigger matches, fill the addendum before @codex review |
Stage Taxonomy (Definition)
- Design: missing requirements, unclear acceptance criteria, privacy/exposure gaps, cross-endpoint invariants not specified.
- Implementation: logic errors, incomplete edge cases, inconsistent ordering/aggregation.
- Testing: missing regression/E2E/contract tests, no reproduction script.
- Review Packaging: PR lacks context, spec, evidence, or minimal repro for Codex to review well.
- Release/Integration: environment constraints (gateway, permissions, paths), deploy-time mismatches.
Cause Taxonomy (Abstract)
- Spec Gap: requirement or invariant not defined.
- Context Gap: Codex lacked PR context (spec, expected behavior, tests).
- Implementation Drift: code diverged from intent or was inconsistent across modules.
- Test Gap: no automated proof for edge cases or invariants.
- Integration Constraint: environment or platform limitations discovered late.
Implementation (Repo-Specific)
Baseline candidate list (optional):
node scripts/ops/pr-retro.cjs \
--since YYYY-MM-DD \
--min-cycles 3 \
--limit 5 \
--out-dir docs/retrospective \
--max-prs 80
Then isolate Codex Cloud feedback per PR:
gh pr view <num> --json reviews,comments --jq '(.reviews + .comments) | map(select(.author.login == "chatgpt-codex-connector"))'
Output notes:
docs/retrospective/YYYY-MM-DD-pr-retro.json keeps summary fields for all PRs; picked contains full detail (reviews/comments/commits/files) for the selected PRs only.docs/retrospective/YYYY-MM-DD-pr-retro.csv is built from the picked list.
Risk-Layer Gate (Preventive)
Before requesting @codex review, check .github/PULL_REQUEST_TEMPLATE.md:
- If any Risk Layer Trigger is checked, you MUST fill the Risk Layer Addendum.
- Provide rules/invariants, boundary matrix (>=3), and evidence (tests or repro).
- Summarize these items in Codex Context so Codex sees the delta clearly.
Evidence Rules
- Each PR must cite at least 1 evidence item.
- If Codex feedback is generic, mark low-signal and rely on follow-up fixes or PR gate docs.
- Do not infer root cause without a traceable artifact.
Common Mistakes
- Treating Codex review count as the root cause.
- Ignoring PR context quality (tests, spec links, repro steps).
- Mixing symptoms (bug) with stage cause (missing invariant).
- Skipping frontend/backend split on mixed PRs.
- Triggering @codex review without completing the risk-layer addendum.
Rationalization Table
| Excuse |
Reality |
| "Codex asked again, so it's Codex's fault" |
Repeated reviews usually reflect missing context or gaps in our stages. |
| "Review cycles are enough" |
Cycles show churn, not cause. Evidence is required. |
| "Titles explain the issue" |
Titles are symptoms, not root causes. |
| "We fixed it later, so root cause is obvious" |
Fixes show symptom; stage attribution still required. |
| "Template is optional" |
Risk-layer addendum is mandatory when any trigger matches. |
Red Flags - STOP
- No evidence chain from Codex feedback to code change.
- All Codex comments are generic and no follow-up fixes exist.
- Root cause stated without stage attribution.
- Evidence relies only on PR title or description.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: pr-review-cycle-retro3description: Use when a team sees repeated @codex review cycles or Codex Cloud feedback churn and needs root-cause attribution by development stage.4---56# Codex Review Churn Analysis (PR Retrospective)78## Overview910Explain why Codex Cloud review had to be re-run. Attribute causes to specific development stages, not just PR outcomes.1112## When to Use1314- Multiple @codex review cycles on the same PR.15- The same feedback appears across successive Codex reviews.16- Follow-up fix PRs exist shortly after merge.17- You need stage-level causes (design / implementation / testing / review packaging / release).1819When NOT to use:2021- Human-review-only churn.22- Pure formatting or mechanical PRs.2324## Core Pattern25261. **Select**: Find PRs with Codex review churn (comment -> code update -> Codex review).272. **Isolate**: Filter only Codex Cloud reviews and actionable feedback.283. **Evidence**: Collect a traceable chain (Codex feedback -> code change or follow-up fix).294. **Classify**: Assign primary + secondary stage causes.305. **Abstract**: Roll causes into a stable taxonomy.316. **Aggregate**: Summarize causes across frontend/backends.327. **Prevent**: Enforce the PR template risk-layer gate before any future @codex review.3334## Quick Reference3536| Item | Rule |37| ----------------- | ---------------------------------------------------------------- |38| Codex cycle | Codex review comment -> code update -> new Codex review |39| Evidence | Codex comment + fix commit OR follow-up fix PR OR regression doc |40| Stage attribution | design / implementation / testing / review packaging / release |41| Mixed PR | record both frontend and backend impact |42| Noise guard | if Codex comments are generic, mark low-signal |43| Risk-layer gate | if any trigger matches, fill the addendum before @codex review |4445## Stage Taxonomy (Definition)4647- **Design**: missing requirements, unclear acceptance criteria, privacy/exposure gaps, cross-endpoint invariants not specified.48- **Implementation**: logic errors, incomplete edge cases, inconsistent ordering/aggregation.49- **Testing**: missing regression/E2E/contract tests, no reproduction script.50- **Review Packaging**: PR lacks context, spec, evidence, or minimal repro for Codex to review well.51- **Release/Integration**: environment constraints (gateway, permissions, paths), deploy-time mismatches.5253## Cause Taxonomy (Abstract)5455- **Spec Gap**: requirement or invariant not defined.56- **Context Gap**: Codex lacked PR context (spec, expected behavior, tests).57- **Implementation Drift**: code diverged from intent or was inconsistent across modules.58- **Test Gap**: no automated proof for edge cases or invariants.59- **Integration Constraint**: environment or platform limitations discovered late.6061## Implementation (Repo-Specific)6263Baseline candidate list (optional):6465```bash66node scripts/ops/pr-retro.cjs \67 --since YYYY-MM-DD \68 --min-cycles 3 \69 --limit 5 \70 --out-dir docs/retrospective \71 --max-prs 8072```7374Then isolate Codex Cloud feedback per PR:7576```bash77gh pr view <num> --json reviews,comments --jq '(.reviews + .comments) | map(select(.author.login == "chatgpt-codex-connector"))'78```7980Output notes:8182- `docs/retrospective/YYYY-MM-DD-pr-retro.json` keeps summary fields for all PRs; `picked` contains full detail (reviews/comments/commits/files) for the selected PRs only.83- `docs/retrospective/YYYY-MM-DD-pr-retro.csv` is built from the `picked` list.8485## Risk-Layer Gate (Preventive)8687Before requesting @codex review, check `.github/PULL_REQUEST_TEMPLATE.md`:8889- If any **Risk Layer Trigger** is checked, you MUST fill the **Risk Layer Addendum**.90- Provide rules/invariants, boundary matrix (>=3), and evidence (tests or repro).91- Summarize these items in **Codex Context** so Codex sees the delta clearly.9293## Evidence Rules9495- Each PR must cite at least 1 evidence item.96- If Codex feedback is generic, mark **low-signal** and rely on follow-up fixes or PR gate docs.97- Do not infer root cause without a traceable artifact.9899## Common Mistakes100101- Treating Codex review count as the root cause.102- Ignoring PR context quality (tests, spec links, repro steps).103- Mixing symptoms (bug) with stage cause (missing invariant).104- Skipping frontend/backend split on mixed PRs.105- Triggering @codex review without completing the risk-layer addendum.106107## Rationalization Table108109| Excuse | Reality |110| --------------------------------------------- | ----------------------------------------------------------------------- |111| "Codex asked again, so it's Codex's fault" | Repeated reviews usually reflect missing context or gaps in our stages. |112| "Review cycles are enough" | Cycles show churn, not cause. Evidence is required. |113| "Titles explain the issue" | Titles are symptoms, not root causes. |114| "We fixed it later, so root cause is obvious" | Fixes show symptom; stage attribution still required. |115| "Template is optional" | Risk-layer addendum is mandatory when any trigger matches. |116117## Red Flags - STOP118119- No evidence chain from Codex feedback to code change.120- All Codex comments are generic and no follow-up fixes exist.121- Root cause stated without stage attribution.122- Evidence relies only on PR title or description.123124---125> Converted and distributed by [TomeVault](https://tomevault.io/claim/victorgpt) — claim your Tome and manage your conversions.126<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io