codex-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# codex-review

Generate a paste-ready prompt for the user to run in their Codex CLI session. The user wants
the prompt to take to Codex. They do NOT want this skill to invoke Codex.

## The hard rule

**Never invoke Codex.** Specifically:

- Do not run `codex review`, `codex …`, or any external review binary via Bash/PowerShell.
- Do not spawn a subprocess that wraps Codex.
- Do not use the `general-purpose` agent to "simulate" a Codex review.
- Do not approximate Codex's output yourself.

If the user explicitly types "and run it" or similar — confirm verbally that the workflow is
prompt-only and ask them to paste it into Codex themselves. The whole point of this skill is
to remove the recurring failure mode where Claude tried to run Codex unprompted.

## Step 1 — gather context

Use read-only tools (Bash for `git diff`, Read for files, Grep for context). Collect:

1. **Diff scope.** Run `git diff --stat <base>...HEAD` (default base: `origin/main` if it
   exists, otherwise `main`, otherwise `HEAD~1`). If the user named files or a branch, scope
   to those.
2. **Changed files list** with rough line counts.
3. **Recent test output** if mentioned in the conversation or visible in `pytest`-style
   artifacts (most recent run in `.pytest_cache/`, or a STATUS.md/log entry citing test
   counts).
4. **Project context** — read the project's `CLAUDE.md` (top portion) to get the project's
   name, layered architecture, and conventions. This goes in the prompt's "context" block so
   Codex knows what it's looking at.
5. **What changed semantically** — skim the diff and group changes by intent (e.g., "added
   load-time access filter", "schema bump v2→v3", "regression tests for streaming path").

If git is not available or the working tree has no diff, ask the user to point at the files
they want reviewed.

## Step 2 — draft the prompt

Output exactly one fenced markdown block. The block contains:

````markdown
# Codex review request — <branch or scope>

## Project context
- **Project:** <name from CLAUDE.md or pyproject.toml>
- **Stack:** <language(s), key libraries>
- **Architecture:** <one-line summary lifted from CLAUDE.md>

## What changed
- <bullet per semantic change group, with file refs>
- <bullet …>

## Diff scope
- Base: `<base ref>` · Head: `<head ref>`
- Files changed: <N> · Lines: +<add>/-<del>
- Key files:
  - `path/to/file.py` — <one-line purpose>
  - …

## Test state
- <pytest counts, e.g., "257/257 passing as of <date>">
- <any tests added/modified in this diff>

## Specific review asks

Categorize findings as **security-meaningful** / **operator-signal** / **nice-to-have**.

1. <ask 1 — correctness against the stated intent>
2. <ask 2 — edge cases the existing tests might not cover>
3. <ask 3 — regressions in code paths outside the diff that use changed symbols>
4. <ask 4 — API contract / public interface stability>
5. <ask 5 — anything project-specific worth focusing on (auth, access, schema, citation discipline, etc.)>

## Out of scope
- <things the user does NOT want reviewed (e.g., "ignore the lock file changes")>

## How to report findings
- Express each finding as an **appended** section (e.g. "Phase 2.5 — <finding>") — do not edit, rewrite, or inline-patch the original code or this prompt. Additive only, so the original and the critique stay separable.

---

Paste this into your Codex CLI and bring the response back. Don't act on findings until I see them.
````

After the fenced block, output one short closing line: **"Paste this into Codex and bring the response back."**

## Step 3 — what NOT to add

- No commentary about what Codex will probably say.
- No predictions about whether the change will pass review.
- No suggestions to "just look at it yourself first."
- No invocations of `Bash codex …` or any agent that would simulate the review.

## Quality bar

A good prompt is **specific to this diff**. It names files, names test counts, names the
semantic shape of the change. A generic "please review my code" template is a failure.

If the diff is empty or unparseable, say so and ask the user to clarify scope rather than
generating a hollow prompt.

## Why this skill exists

In the audit window (2026-05-12 → 2026-05-21), Claude repeatedly tried to invoke Codex when
only a prompt was wanted, costing time and sometimes credits. ADR-0010 (the streaming-chat
trust-zone drift catch) demonstrated that Codex review on every feature-branch commit catches
load-bearing bugs — but only if the workflow is reliable. This skill makes the prompt-gen
step the reliable default.

Related: `~/.claude/CLAUDE.md` §"Codex review workflow" enshrines this as a user-level rule.

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness