codex-review

What this skill does

# Codex Review

Use this skill when you need a second perspective on work in progress. Codex excels at identifying gaps in reasoning, missing requirements, architectural concerns, and flawed assumptions - especially early in the planning process when issues are cheapest to fix.

## When to Use

Invoke this skill when the user wants an external perspective, especially during early phases:
- Brainstorming sessions - validating ideas and approaches
- Requirements gathering - checking for gaps or contradictions
- Design documents - reviewing architecture and technical decisions
- Implementation plans - validating approach before writing code
- Occasionally: reviewing code or diffs when explicitly requested

## How to Invoke Codex

Codex runs in non-interactive mode via `codex exec`. Pass all content directly via stdin.

**Command template:**
```bash
printf "%s" "$CONTENT_TO_REVIEW" | codex exec \
  -m "gpt-5.1-codex-max" \
  -c 'model_reasoning_effort="high"' \
  -s read-only \
  -
```

The `-` at the end tells Codex to read the prompt from stdin. Use `printf "%s"` instead of `echo` to safely handle content with backslashes or leading dashes.

## Preparing the Content

Before invoking Codex, gather all relevant context into a single prompt. Codex has no access to the filesystem or any context beyond what you provide.

**Important:** Strip sensitive data (API keys, tokens, credentials, secrets) from content before sending to Codex. If the context is unclear or you need specific focus areas, prompt the user for guidance.

**For brainstorming or ideas:**
```
## Review Request: Idea Validation

Please review the following ideas/approach for gaps, risks, and flawed assumptions.

### Proposal:
<the idea, approach, or brainstorm output>

### Context:
<problem being solved, constraints, goals>
```

**For requirements:**
```
## Review Request: Requirements

Please review these requirements for completeness, contradictions, and missing edge cases.

### Requirements:
<the requirements>

### Context:
<what system/feature these are for>
```

**For design documents:**
```
## Review Request: Design

Please review the following design for gaps, risks, and potential issues.

### Design:
<the design document or architecture>

### Context:
<background, constraints, goals>
```

**For code or diffs (when explicitly requested):**

Fetch the content using the project's VCS (git, jj, etc.) with color codes stripped. Frame the request appropriately:
```
## Review Request: Implementation

Please review the following for correctness, edge cases, and potential issues.

### Content:
<code or diff>

### Context:
<what this does, why it was changed>
```

## The Review Prompt

Always append these instructions to ensure structured output:

```
---

## Output Format

Provide your review in the following sections only:

### Blocking Issues
Issues that MUST be addressed before proceeding. These are bugs, security vulnerabilities, logic errors, or design flaws that would cause problems.

### Non-blocking Issues
Suggestions for improvement that are not critical. Style concerns, minor optimizations, or alternative approaches worth considering.

### Outstanding Questions
Questions that need clarification from the author. Ambiguities in requirements, unclear design decisions, or missing context.

### Further Ideas
Optional enhancements or future considerations. Ideas that could improve the work but are out of scope for now.

If a section has no items, write "None identified."
```

## Full Example

```bash
# Build the prompt with content and output format instructions
PROMPT=$(cat <<'REVIEW_EOF'
## Review Request: Design

Please review the following design for gaps, risks, and potential issues.

### Design:
We're building a caching layer for our API. The plan is:
1. Use Redis for distributed caching
2. Cache all GET responses for 5 minutes
3. Invalidate on any write operation to related resources
4. Fall back to database on cache miss

### Context:
- High-traffic API (~10k requests/minute)
- Eventually consistent is acceptable
- Must not serve stale data after writes

### Additional Focus:
Pay attention to cache invalidation edge cases.

---

## Output Format

Provide your review in the following sections only:

### Blocking Issues
Issues that MUST be addressed before proceeding. These are bugs, security vulnerabilities, logic errors, or design flaws that would cause problems.

### Non-blocking Issues
Suggestions for improvement that are not critical. Style concerns, minor optimizations, or alternative approaches worth considering.

### Outstanding Questions
Questions that need clarification from the author. Ambiguities in requirements, unclear design decisions, or missing context.

### Further Ideas
Optional enhancements or future considerations. Ideas that could improve the work but are out of scope for now.

If a section has no items, write "None identified."
REVIEW_EOF
)

# Invoke Codex
printf "%s" "$PROMPT" | codex exec \
  -m "gpt-5.1-codex-max" \
  -c 'model_reasoning_effort="high"' \
  -s read-only \
  -
```

## After the Review

1. Display the full review report to the user
2. Prompt the user to:
   - Answer any outstanding questions
   - Address blocking issues (these should be resolved)
   - Comment on non-blocking issues and further ideas (accept, reject, or defer)
3. If the user wants to address issues, help them implement the fixes
4. Consider re-running the review after significant changes