codex-review

name	codex-review
description	Request an external review from Codex (OpenAI) to get a second perspective on designs, implementations, diffs, or architecture decisions

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:

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

# 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