Codex Code Review

Codex Code Review Loop

Overview

This skill orchestrates the complete remediation workflow for code under review by the codex agent. It handles:

• Requesting reviews from codex using the codex --full-auto c CLI
• Parsing review output to identify P0 (security/correctness), P1 (reliability), P2-P4 (quality) findings
• Remediating critical issues through up to 3 review-fix-review cycles
• Deferring quality improvements to backlog with implementation plans and origin:ai-review labels
• Monorepo handling for selective file commits when working alongside other agents
• Circuit breaker escalation after 3 cycles if P0/P1 issues persist

When to Use

Trigger this skill when code requires codex review. Common usage patterns:

• "codex review this code" — Initiate review loop on current changes
• "run codex review on my changes" — Same as above
• "codex review --uncommitted" — Review all uncommitted changes
• "codex review --commit <SHA>" — Review specific commit in monorepo
• Questions about codex (e.g., "how does codex work?") — Do not trigger this skill; answer directly

Do not trigger on questions. Only activate for direct review requests.

---

The Review Loop: Step by Step

ENTRY: User requests codex review or skill is triggered by "codex review" in a message

┌──────────────────────────┐
│ 1. INVOKE CODEX REVIEW   │ ← Run: codex --full-auto c [--uncommitted|--commit <SHA>|--base <BRANCH>]
└──────┬───────────────────┘   Output goes to .agent/reviews/review-<timestamp>.md
       │
       ▼
┌──────────────────────────┐
│ 2. READ & PARSE REVIEW   │ ← Read markdown file, extract P0/P1/P2-P4 findings and verdict
└──────┬───────────────────┘
       │
       ├─────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
  ANY P0/P1?              NO         FILE P2-P4 ISSUES → Exit loop
       │                              (via backlog CLI)
       │ YES                         Create issue per finding with
       │                             - label: origin:ai-review
  ┌────────────────┐                - Implementation plan
  │ 3. REMEDIATE   │                - Priority (P2 or P3)
  │ P0/P1 FINDINGS │
  └────┬───────────┘
       │ (amend commit or new changes)
       │
       ▼
  ┌──────────────────────┐
  │ 4. LOOP CHECK        │
  │ Cycle count < 3?     │
  └────┬───────────────┬─┘
       │ YES           │ NO
       │               └─→ SUMMARIZE & ASK USER TO CONTINUE
       │                   (or exit if user declines)
       ▼
  Re-run codex review (step 1, same files/scope)
  Loop back to step 2

Cycle Management

• Cycle 1: Initial review after implementation
• Cycle 2: After first remediation
• Cycle 3: After second remediation
• After Cycle 3: If P0/P1 remain, stop. Summarize findings and ask user if they want to continue (rare; usually indicates design-level issues)

---

Decision Tree: Handling Findings

When review shows P0/P1 findings (verdict: REQUEST CHANGES)

1. Read the codex review markdown file 2. Extract each P0 and P1 finding with:

• Finding ID and title
• File location
• Suggested fix

3. Fix ONLY the cited findings in the code 4. Do NOT refactor, do NOT introduce new functionality 5. If a fix requires significant design changes, note this and let codex re-evaluate on next cycle 6. Amend your commit OR create a new one (user's choice via git config; by default amend to keep one commit at end) 7. Increment cycle counter and re-run codex review

When review shows P2-P4 findings (verdict: APPROVE or PASS WITH ISSUES)

1. For each P2/P3 finding, decide:

• Fix now: You have discretion; implement the improvement in the same cycle
• Defer: Create a backlog issue with:
• Type label: remediation
• Severity label: P2 or P3
• Custom label: origin:ai-review
• Implementation plan based on codex's suggested approach
• Acceptance criteria from the review

2. Examples:

   # P2 finding deferred to backlog
   backlog task create "Code clarity: add docstring to validateInput()" \
     -d "Review finding: missing documentation on public function" \
     -l remediation -p 2 \
     --ac "Add docstring explaining parameter types and return value" \
     --plan "Add JSDoc comment above function definition per project style"

When review shows no findings (verdict: APPROVE)

Exit the loop. Code is clean. Proceed to test review (if applicable) or commit for merge.

---

Monorepo Handling

In a monorepo with multiple agents, be selective about what you commit and what scope you review.

Scenario 1: Only Your Changes

If the working directory has ONLY your changes:

codex --full-auto c --uncommitted

Commit your changes once review loop completes.

Scenario 2: Mixed Changes (You + Other Agents)

If there are untracked or uncommitted changes from other agents: 1. Commit ONLY your files first:

   git add <your-files-only>
   git commit -m "Your commit message"

2. Note the commit SHA 3. Run review on your commit:

   codex --full-auto c --commit <SHA>

4. Remediate by amending your commit:

   git add <fixed-files>
   git commit --amend --no-edit

(Preserve the original message; the amend adds the fixes) 5. Loop back to review as normal

Result: One clean commit with your changes and fixes. Other agents' work remains separate.

---

File Locations

• Review output: .agent/reviews/review-<timestamp>.md (relative to project root)
• One review file per cycle — new file created on each codex --full-auto c invocation
• Always read the latest file — check the timestamp to ensure you're reading the current cycle's review

---

Bundled References

See `references/codex-cli-reference.md` for:

• Complete codex CLI syntax and invocation patterns
• How to select --uncommitted vs. --commit vs. --base
• When to use each mode

See `references/review-format.md` for:

• Structure of the review markdown output
• How to parse P0/P1/P2/P3 sections
• How to identify the verdict (APPROVE / REQUEST CHANGES / BLOCKED)
• Example review output

See `references/backlog-integration.md` for:

• How to create backlog issues from deferred findings
• Label and priority conventions
• Implementation plan templates
• Examples of issues filed from reviews

See `scripts/parse_codex_review.sh` for:

• Helper script to extract findings from review markdown
• Counts P0/P1/P2/P3 per cycle
• Quick verdict extraction

---

Key Rules

1. All P0/P1 must be fixed before exiting the loop. No exceptions. 2. P2-P4 can be deferred to backlog or fixed at your discretion. 3. File one issue per finding — do not batch unrelated P2/P3s into one issue. 4. Deferred issues must include a plan — codex identified the problem; you provide the structured approach. 5. Amend commits (not new commits) during remediation so you end with one clean commit. 6. Max 3 review cycles — after cycle 3, if P0/P1 remain, summarize and ask user to continue. 7. In monorepos, commit selectively — review and fix only the files you touched.

---

Escalation: When Circuit Breaker Triggers

After 3 review cycles, if P0/P1 findings persist:

1. Stop remediating. Do not attempt a 4th cycle. 2. Produce a structured summary including:

• What was attempted in each cycle
• What P0/P1 findings remain
• Why they persist (agent assessment — design issue? conflicting requirements? ambiguity in spec?)
• Recommended human action

3. Present this summary to the user and ask how to proceed.

Escalation usually indicates the original task spec needs clarification or the code requires architectural changes beyond remediation scope.

---

Integration with Other Skills

• backlog-md: File deferred P2/P3 findings using backlog task create with origin:ai-review label
• git-ops: Commit handling, amending, and selective staging in monorepos
• requesting-code-review: Use after codex review loop completes if human code review is also required

---

Quick Reference: The Full Workflow

1. User: "codex review"
        │
        ▼
2. Invoke: codex --full-auto c --uncommitted
        │
        ▼
3. Read: .agent/reviews/review-<timestamp>.md
        │
        ├─────────────────────────────────────────┐
        ▼                                         ▼
   P0/P1 FOUND?              NO         FILE P2-P4 ISSUES
   ├─ YES: Fix + Loop ────────────────► backlog task create ... --plan "..."
   └─ NO: File P2-P4 → Exit            (each finding = one issue)
        │
        ├─ Cycle 1 → Fix → Review
        ├─ Cycle 2 → Fix → Review
        ├─ Cycle 3 → Fix → Review
        │
        └─ If P0/P1 remain → Summarize + Ask User
                │
                └─► Continue? (rare) / Stop & Escalate

Backlog Integration: Filing Deferred Review Findings

When codex review identifies P2-P4 findings that you choose not to fix immediately, file them as backlog issues with proper labeling and implementation plans.

---

Issue Filing Rules

1. One issue per finding — Do not batch unrelated findings into a single issue 2. Type label required — Use remediation for all deferred review findings 3. Severity label — Use P2 or P3 (not P4 unless explicitly from review) 4. Origin label — Tag with origin:ai-review so findings are traceable to this review cycle 5. Include plan — Codex identified the problem; you provide the structured approach based on their suggestion

---

Command Template

backlog task create "Title of the finding" \
  -d "Description of the issue" \
  -l remediation \
  -p 2 \
  --ac "Acceptance criteria from review" \
  --plan "Implementation plan based on codex suggestion"

Required Parameters

• `-l remediation` — Type label (always remediation for review findings)
• `-p 2` or `-p 3` — Priority (P2 or P3 from the review)
• `--ac "..."` — Acceptance criteria (what makes this issue done?)
• `--plan "..."` — Implementation plan (how to approach the fix)

---

Field Mapping from Review

Map codex review findings to backlog fields:

---

Examples

Example 1: Documentation Improvement (P2)

Codex Finding:

#### P2-001: Missing JSDoc for `setToken()`

**File:** `src/auth.ts:30`
**Issue:** Public function `setToken()` has no documentation.
**Recommendation:** Add JSDoc explaining parameter types, side effects (e.g., updates localStorage), and return value.

Backlog Issue:

backlog task create "Auth: Add JSDoc to setToken() function" \
  -d "File: \`src/auth.ts:30\`\n\nPublic function setToken() lacks documentation. This impairs developer experience and IDE support." \
  -l remediation \
  -p 2 \
  --ac "JSDoc comment added above setToken() with parameter types, side effects, and return value documented" \
  --plan "Add JSDoc comment block above the setToken() function definition. Include @param for all parameters, @returns, and @description of side effects (localStorage mutation)."

Example 2: Error Handling Gap (P2)

Codex Finding:

#### P2-003: Missing error handling in callback chain

**File:** `src/handlers/webhook.ts:105-112`
**Issue:** The Promise chain in handleWebhook() has a `.then()` but no `.catch()` for network failures.
**Recommendation:** Add error boundary or `.catch()` to log and recover gracefully from network errors.

Backlog Issue:

backlog task create "Webhooks: Add error handling to handleWebhook callback" \
  -d "File: \`src/handlers/webhook.ts:105-112\`\n\nThe Promise chain lacks error handling for network failures, potentially causing unhandled rejections." \
  -l remediation \
  -p 2 \
  --ac "Promise rejection handled gracefully with error logging and fallback behavior" \
  --plan "Add .catch() to the Promise chain in handleWebhook(). Log errors to monitoring system. Implement exponential backoff or dead-letter queue for failed webhooks."

Example 3: Test Coverage Gap (P2)

Codex Finding:

#### P2-005: Missing edge case test for empty list

**File:** `src/utils/processItems.test.ts`
**Issue:** Tests only cover non-empty lists. Edge case: empty list [] is untested.
**Recommendation:** Add test case for `processItems([])` to verify handling of empty input.

Backlog Issue:

backlog task create "Tests: Add edge case test for empty list in processItems()" \
  -d "File: \`src/utils/processItems.test.ts\`\n\nEdge case for empty input is untested. Current tests only cover non-empty lists." \
  -l remediation \
  -p 2 \
  --ac "New test case for processItems([]) exists and passes" \
  --plan "Add test case: describe('empty list', () => { expect(processItems([])).toEqual([...]); });. Verify correct behavior for empty input based on function contract."

Example 4: Code Clarity (P3)

Codex Finding:

#### P3-002: Variable name could be clearer

**File:** `src/lib/parser.ts:67`
**Issue:** Variable `tmp` is ambiguous. Unclear what it holds (temp result? temporary state?).
**Recommendation:** Rename to something descriptive like `parsedToken` or `intermediateResult`.

Backlog Issue:

backlog task create "Code clarity: Rename ambiguous variable in parser" \
  -d "File: \`src/lib/parser.ts:67\`\n\nVariable \`tmp\` is ambiguous and reduces code clarity." \
  -l remediation \
  -p 3 \
  --ac "Variable renamed to something descriptive; all references updated; tests still pass" \
  --plan "Rename \`tmp\` to \`parsedToken\` (or similar based on what it contains). Update all references in the parseInput() function and any calling code."

---

Labels and Conventions

Type Label (Required)

Always use `-l remediation` for all findings from codex review. This distinguishes them from other issue types.

Additional Labels (Optional)

After -l remediation, you can add custom labels for organization:

backlog task create "Title" \
  -l remediation \
  -p 2 \
  -l security        # Additional custom label if relevant
  -l performance     # Additional custom label if relevant
  --ac "..." \
  --plan "..."

Severity Priority

• P2 — Important for code quality or reliability; address in current or next sprint
• P3 — Nice-to-have improvements; lower priority; backlog candidate

---

Integration Timing

When to File

After codex review completes:

• P0/P1 findings are fixed (loop exits)
• P2/P4 findings are ready to be deferred

File issues before exiting the skill workflow or immediately after the review loop completes.

What to Include in the Plan

The implementation plan should include: 1. What to change — Specific file, function, or area 2. How to change it — Based on codex's suggested approach 3. Expected outcome — What the code should look like after 4. Any dependencies — E.g., "Requires updating other tests" or "Follows pattern X from module Y"

---

Backlog CLI Examples

List recent remediation issues

backlog task list -l remediation --plain

Search for issues from this review cycle

backlog search "origin:ai-review" --plain

Work an issue

backlog task 42 --plain          # Read all details
backlog task edit 42 -s "In Progress" -a @myself
backlog task edit 42 --final-summary "Issue fixed via PR #123"
backlog task edit 42 -s Done

---

Notes

• Do not file P0/P1 findings — These are fixed during the review loop, not deferred
• Do file P2/P3 findings — You decide whether to fix immediately or defer
• One issue per finding — Keeps backlog granular and trackable
• Use the origin label — origin:ai-review makes these findings searchable and traces them back to the review workflow
• Include a plan — Codex identified the problem; your plan shows you understand the fix approach

See the backlog-md skill documentation for complete CLI reference.

Codex CLI Reference

Invocation

codex --full-auto c [--uncommitted|--base <BRANCH>|--commit <SHA>]

Modes

--uncommitted (Recommended for single-repo or isolated work)

Reviews all uncommitted and unstaged changes in the current working directory.

codex --full-auto c --uncommitted

Use when:

• You have only your changes in the working directory
• No other agents' work is mixed in
• You want to review everything you've modified since the last commit

Output: Review markdown written to .agent/reviews/review-<timestamp>.md

--base <BRANCH> (Branch comparison)

Reviews all changes between the specified branch and HEAD.

codex --full-auto c --base origin/main
codex --full-auto c --base main

Use when:

• You want to compare your current branch against a specific baseline
• In pull request workflows to see what you've changed relative to main

Output: Review markdown written to .agent/reviews/review-<timestamp>.md

--commit <SHA> (Specific commit - Monorepo safe)

Reviews only the specified commit's changes. Useful in monorepos where multiple agents work simultaneously.

codex --full-auto c --commit abc1234
codex --full-auto c --commit HEAD

Use when:

• You've committed your changes to the repository
• Other agents have uncommitted or untracked changes in the working directory
• You want to review ONLY your commit, not anyone else's work

Output: Review markdown written to .agent/reviews/review-<timestamp>.md

Monorepo workflow:

# 1. Commit only your changes
git add <your-files>
git commit -m "Your change"

# 2. Get the commit SHA (e.g., abc1234)
COMMIT_SHA=$(git rev-parse HEAD)

# 3. Review that specific commit
codex --full-auto c --commit $COMMIT_SHA

# 4. Read and process review at .agent/reviews/review-<timestamp>.md

# 5. If fixes needed, amend the commit
git add <fixed-files>
git commit --amend --no-edit

# 6. Loop back to step 3 for re-review

---

Output Format

After running codex --full-auto c, codex generates a markdown review file at:

.agent/reviews/review-<TIMESTAMP>.md

Where <TIMESTAMP> is in format: YYYYMMDD-HHMMSS (e.g., 20260218-143021)

The review markdown contains:

• Summary of files reviewed
• Iteration number (1 of 3, 2 of 3, etc.)
• Findings organized by severity (P0, P1, P2, P3)
• Each finding includes:
• Finding ID (e.g., P0-001)
• Title
• File and line range
• Description of the issue
• Impact
• Suggested fix
• Overall verdict: APPROVE / REQUEST CHANGES / BLOCKED

See references/review-format.md for detailed format specification.

---

Output Directory

Codex always writes reviews to .agent/reviews/ relative to the project root.

To locate the latest review:

ls -t .agent/reviews/review-*.md | head -1

To read the latest review:

cat "$(ls -t .agent/reviews/review-*.md | head -1)"

---

Environment Variables

Optional environment variables that affect codex behavior (if applicable):

• CODEX_TIMEOUT — Max seconds for codex to spend on review (default varies)
• CODEX_MAX_BUDGET — Max USD budget for review invocation (default varies)

Check codex --help for current supported environment variables.

---

Exit Codes

• 0 — Review completed successfully; review file written to .agent/reviews/
• Non-zero — Error (codex CLI failure, git error, etc.); check stderr for details

---

Diff Size Limits

If your diff is extremely large (>2000 lines), codex may truncate or reject it. In this case:

1. Review a smaller subset of files using path filters (if available) 2. Split the work into smaller commits 3. Review each commit separately

Contact codex documentation or maintainers for guidance on handling large diffs.

Codex Review Output Format

Overview

After running codex --full-auto c, the review output is written as markdown to .agent/reviews/review-<TIMESTAMP>.md.

This document specifies the format so you can parse findings programmatically or manually.

---

Top-Level Structure

# Code Review: [Brief description of what was reviewed]

**Files reviewed:** [comma-separated list of file paths]
**Iteration:** N of 3

### Findings

[Findings grouped by severity: P0, P1, P2, P3]

### Summary

[Statistics and verdict]

---

Findings Section

P0 Findings (Security/Correctness Critical)

These MUST be fixed before exiting the review loop.

#### P0-001: [Title of the finding]

**File:** `path/to/file.rs:45-52`
**Issue:** [Description of what is wrong]
**Impact:** [What happens if not fixed — security risk, data loss, crash, etc.]
**Suggested fix:** [Specific, actionable guidance on how to fix it]

P1 Findings (Reliability/Edge Cases)

These MUST be fixed before exiting the review loop.

#### P1-001: [Title of the finding]

**File:** `path/to/module.ts:120`
**Issue:** [Description of what is wrong]
**Impact:** [What happens if not fixed — unhandled errors, resource leaks, etc.]
**Suggested fix:** [Specific guidance]

P2 Findings (Code Quality)

Can be fixed now or deferred to backlog.

#### P2-001: [Title of the finding]

**File:** `path/to/file.py:88-95`
**Issue:** [What could be improved]
**Recommendation:** [How to improve it]

P3 Findings (Style/Preferences)

Can be fixed now or deferred. Usually low priority.

#### P3-001: [Title of the finding]

**File:** `path/to/file.go:50`
**Issue:** [Style or preference issue]
**Recommendation:** [Suggested change]

---

Summary Section

### Summary

- **P0:** N findings (MUST fix)
- **P1:** N findings (MUST fix)
- **P2:** N findings (optional)
- **P3:** N findings (optional)

**Verdict:** APPROVE / REQUEST CHANGES / BLOCKED

Verdict Meanings

---

Complete Example

# Code Review: Auth Module - Token Refresh

**Files reviewed:** `src/auth.ts`, `src/auth.test.ts`
**Iteration:** 2 of 3

### Findings

#### P0-001: Race condition in token refresh

**File:** `src/auth.ts:45-52`
**Issue:** Multiple concurrent calls to `refreshToken()` can issue multiple refresh requests simultaneously, leading to issued but unused tokens. The check for "in-flight refresh" is not atomic.
**Impact:** Token exhaustion. If tokens have a per-user limit, attackers could exhaust the token quota.
**Suggested fix:** Use a promise-based semaphore or mutex to ensure only one refresh request is in flight at a time. See the `p-queue` or native `AbortController` pattern for inspiration.

#### P1-001: Unhandled promise rejection

**File:** `src/auth.ts:78`
**Issue:** `refreshToken()` returns a promise that can reject (network error, 401, etc.), but callers may not always `catch()` the rejection.
**Impact:** Unhandled rejections cause app crashes. Users lose their session without feedback.
**Suggested fix:** Either (1) ensure all callers have `.catch()`, or (2) wrap the promise chain with an error boundary in the auth module itself.

#### P2-001: Missing JSDoc for `setToken()`

**File:** `src/auth.ts:30`
**Issue:** Public function `setToken()` has no documentation.
**Recommendation:** Add JSDoc explaining parameter types, side effects (e.g., updates localStorage), and return value.

### Summary

- **P0:** 1 finding (MUST fix)
- **P1:** 1 finding (MUST fix)
- **P2:** 1 finding (optional)
- **P3:** 0 findings

**Verdict:** REQUEST CHANGES

---

Parsing Tips

Count Findings by Severity

Search for headings #### P0-, #### P1-, #### P2-, #### P3- and count occurrences.

grep -c "^#### P0-" review.md  # Count P0 findings
grep -c "^#### P1-" review.md  # Count P1 findings
grep -c "^#### P2-" review.md  # Count P2 findings
grep -c "^#### P3-" review.md  # Count P3 findings

Extract Verdict

Look for the line starting with **Verdict:** in the Summary section.

grep "^\\*\\*Verdict:\\*\\*" review.md

Extract File Locations

Each finding has a **File:** line. Extract file paths and line ranges:

grep "^\*\*File:\*\*" review.md
# Example output:
# **File:** `src/auth.ts:45-52`
# **File:** `src/auth.ts:78`

Check Iteration Count

Look for the line **Iteration:** near the top.

grep "^\\*\\*Iteration:\\*\\*" review.md
# Example output:
# **Iteration:** 2 of 3

---

When No Findings Are Present

If the code is clean, the review still has a "Findings" section but it may be empty:

# Code Review: Auth Module

**Files reviewed:** `src/auth.ts`
**Iteration:** 1 of 3

### Findings

(No findings.)

### Summary

- **P0:** 0 findings
- **P1:** 0 findings
- **P2:** 0 findings
- **P3:** 0 findings

**Verdict:** APPROVE

---

Integration with Remediation Loop

After Reading Review:

1. Count P0 + P1 findings 2. If count > 0:

• Fix each finding per suggested guidance
• Amend or update code
• Re-run codex review (loop back to step 1)

3. If count == 0:

• File issues for P2/P3 findings (if deferring)
• Exit the loop

After 3 Iterations:

If P0/P1 findings still exist, stop remediating and escalate to user.

---

Notes

• Review markdown files are temporary and accumulate in .agent/reviews/. Older reviews can be cleaned up after the remediation loop completes.
• Always read the latest review file (highest timestamp) to ensure you're acting on the current cycle's findings.
• If a finding is disputed, note your disagreement in the remediation and run the review again. Codex will re-evaluate.