cmd-codex-review-unstaged

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codex Review Unstaged <!-- omit in toc -->

Use `codex exec` as an independent reviewer on the working-tree changes Claude just made. Codex sees only the summary + diff (no conversation history), so its critique catches things Claude rationalized into "good enough" during implementation. The output is a prioritized iteration plan — what to fix now, what to defer, what to reject.

- [When to use](#when-to-use)
- [Instructions](#instructions)
- [Codex prompt](#codex-prompt)
- [Output format](#output-format)
- [Notes](#notes)

## When to use

- After Claude finishes a non-trivial implementation pass and before commit
- When the user says "review my changes with codex", "have codex check what I just did", or `/cmd-codex-review-unstaged`
- As an outside cross-check before opening a PR — complements `cmd-pr-follow-up` (Claude self-review) and `cmd-pr-edgecase` (edge-case sweep) by adding a fresh pair of eyes that didn't write the code

## Instructions

### 1. Build Claude's implementation summary

Write a short summary of what was just implemented. Keep it **factual, not promotional**:

- What was the goal?
- What files changed and why?
- What design decisions were made (and what was rejected)?
- What was deliberately deferred (TODOs, follow-ups, scope cuts)?
- What was tested manually vs. covered by automated tests?

This summary anchors codex's review — without it, codex will judge the diff against a generic standard instead of the actual intent.

### 2. Capture the diff

Default scope: **`git diff HEAD`** — captures both staged and unstaged working-tree changes since the last commit.

```bash
DIFF_FILE=$(mktemp -t codex-diff.XXXXXX.patch)
SUMMARY_FILE=$(mktemp -t codex-summary.XXXXXX.md)
OUT_FILE=$(mktemp -t codex-review.XXXXXX.md)

git diff HEAD > "$DIFF_FILE"
git status --short >> "$DIFF_FILE"
```

If the user explicitly asks for unstaged-only or branch diff, swap in:
- Unstaged only: `git diff`
- Branch vs main: `git diff main...HEAD`
- Include untracked: append `git ls-files --others --exclude-standard` separately

Write the summary from step 1 verbatim to `$SUMMARY_FILE` using the Write tool.

**Sanity check before invoking codex:**
- If `$DIFF_FILE` is empty (no changes), tell the user there's nothing to review and stop.
- If the diff is enormous (>50k lines), warn the user — codex will still run but the review quality drops on huge surfaces. Suggest narrowing scope (e.g., per-file or per-phase review).

### 3. Run codex in headless review mode

```bash
codex exec \
  --sandbox read-only \
  --skip-git-repo-check \
  --color never \
  --output-last-message "$OUT_FILE" \
  "$(cat <<PROMPT
You are reviewing a working-tree diff produced by another coding agent (Claude).

You will receive two files:
- $SUMMARY_FILE — Claude's own summary of what it implemented and why
- $DIFF_FILE — the raw \`git diff HEAD\` output plus \`git status --short\`

Read both before reviewing.

You also have access to two skill methodology references (read them before forming your review — they describe what to look for):
- ~/.codex/skills/cmd-pr-follow-up/SKILL.md — post-implementation reflection methodology (incomplete tasks, idiomatic concerns, modularity, simplification, comments/prose)
- ~/.codex/skills/cmd-pr-edgecase/SKILL.md — edge case and failure mode methodology (test gaps, malformed inputs, integration risks)

Apply BOTH methodologies to this diff. Then go further: look for issues those skills do not cover.

Your job:
1. **Correctness bugs** — logic errors, off-by-ones, wrong conditionals, race conditions, incorrect API usage. Cite file:line.
2. **Test gaps** — code paths added without tests, edge cases not covered, regression risks. Cite which test file should exist or be extended.
3. **Edge cases & failure modes** — what happens with empty input, null, concurrent calls, malformed data, network failure, partial state.
4. **Adjacent improvements** — things the diff touches that could be cleaned up in the same pass (dead code nearby, stale comments, naming inconsistencies).
5. **Simplification opportunities** — over-engineering, premature abstraction, defensive code for impossible states, dead branches.
6. **Idiomatic / convention violations** — where the diff diverges from the project's patterns (look at surrounding files in the diff for the local convention).
7. **What Claude likely missed** — read the summary critically. Did Claude defer something that actually matters? Claim test coverage that isn't there? Skip a constraint?
8. **What's good** — 1-3 honest bullets on what the implementation gets right. No flattery.

Constraints:
- Do NOT modify files. This is a read-only review.
- Be specific: cite \`file_path:line_number\` for every finding. Vague critique is useless.
- Rank findings by severity (critical / high / medium / low).
- If the implementation is solid, say so. Do not invent issues.

Output format (markdown):

## Verdict
One sentence: ship-as-is | minor-tweaks | needs-rework | blocked

## Critical / High
[bullets — bugs, missing tests for risky paths, broken invariants — with file:line]

## Medium
[bullets — edge cases, simplification opportunities, idiomatic concerns — with file:line]

## Low / Adjacent
[bullets — nice-to-haves, follow-up TODOs, stale-comment cleanup — with file:line]

## What Claude Likely Missed
[bullets called out from reading the summary against the diff]

## What's Good
[1-3 honest bullets]
PROMPT
)" < /dev/null
```

Stream codex's progress to the user as it runs. Capture the final review from `$OUT_FILE`.

> **Note:** the prompt references `$SUMMARY_FILE` and `$DIFF_FILE` by absolute path. Since codex runs read-only in the same working directory, it will read those tempfiles when instructed. Use full paths in the heredoc (substituted by the shell) so codex can locate them without ambiguity.

From Olshansk/agent-skills, MIT.

More from Olshansk/agent-skills