Codex Review

Skill: Codex review

Purpose

Have a second model (OpenAI Codex) independently re-derive the current analysis from the same data and compare it to Claude's original. Codex gets the question and the metric definitions, but never sees Claude's SQL, numbers, or conclusions — it writes its own queries and computes its own results. The skill then reconciles the two: AGREE, DISAGREE, or PARTIAL per finding. Two models agreeing from independent derivations is strong evidence the analysis is sound; a disagreement points to exactly where to look.

This pairs with /reliability (same model, run N times — tests stability). /codex-review uses a different model once — it tests correctness by independent agreement.

When to Use

• User says /codex-review, "validate with codex", "codex review", "second opinion from codex", "independently verify this", "does codex agree", "cross-check with the other model"
• After producing a finding the user is about to act on and wants a second model to confirm
• Routed here whenever multi-model validation of an analytical result is wanted

Invocation

/codex-review [finding or artifact path] — validate the most recent analysis by default, or scope to a single finding/file if given. Example: /codex-review after answering "What's our 30-day retention?"

Instructions

⛔ HARD GATE — read before anything else

This skill is worthless unless a different model (Codex) does the validation. If Codex is not ready, you (Claude) MUST NOT perform the validation yourself. Claude re-checking Claude's analysis is circular — it produces a confident "validated ✓" that means nothing and actively misleads the student.

The rule: if Step 1's preflight returns a non-empty missing list, your ONLY job this turn is to help the student set up Codex. You may not proceed to Steps 2–7, and you may not substitute any other model, your own reasoning, a re-run of the SQL, or an "approximate" check. There is no fallback that uses Claude. Setup is the task when Codex is missing — completing it is the helpful outcome, not skipping ahead to a verdict.

Step 1 — Preflight: is Codex usable? (decision matrix)

Run the deterministic check:

python3 helpers/provenance/codex_validation.py --check

It returns JSON: {"codex_cli", "plugin", "auth", "missing": [...]}. Route on missing:

• Empty missing → Codex is ready. Go to Step 2.
• "codex_cli" present → the Codex CLI isn't installed. Tell the user to run:

  npm install -g @openai/codex

  (Requires Node.js 18.18+.)
• "plugin" present → the Claude Code plugin isn't installed. Show these commands for the user to paste (the skill cannot run them — they're interactive):

  /plugin marketplace add openai/codex-plugin-cc
  /plugin install codex@openai-codex
  /reload-plugins
  /codex:setup

• "auth" present → Codex is installed but not authenticated. Tell the user to run:

  codex login

  (Sign in with a ChatGPT account or an API key.)

If missing is non-empty, stop after giving the setup step and end the turn with "Once that's done, re-run /codex-review and I'll have Codex check it." The next invocation re-runs --check and proceeds only when missing is empty.

Restart gate. If the student just installed the plugin, also remind them the plugin's tools aren't loaded until they run /reload-plugins — so the sequence is install → /reload-plugins → re-run /codex-review. (auth is best-effort: if --check returns auth: null with the CLI and plugin present, proceed — the live Codex run is the real gate and will surface any login error.)

Keep this simple and one-step-at-a-time: name only the first missing piece, let the student fix it, then re-run the check. Setup may take two or three turns (CLI, then plugin + reload, then login); that is the expected, correct path — not a detour from the "real" work.

Step 2 — Resolve what's being validated

Identify, for the most recent analysis (or the scoped finding):

• The question it answered.
• The metric definitions / scope / time-window Claude used — pull from the metric dictionary (metrics/index.yaml), the analysis design spec, or the analysis itself.
• The active dataset (.knowledge/active.yaml).
• Claude's original result(s) — the headline number(s), the SQL, and the conclusion.

If it's ambiguous what to validate (no recent finding, multiple candidates), ask the user which finding or artifact to check, and offer a path.

Step 3 — Write the validation brief (blind to Claude's numbers)

Create a timestamped run directory: working/codex_validation/<UTC-timestamp>-<question-slug>/.

Write brief.md in it containing ONLY what Codex needs to answer the same question the same way, independently:

• The question.
• The metric definition(s), scope, and time-window (so Codex measures the same thing).
• The active dataset id and how to reach the data: read .knowledge/active.yaml, the active dataset's .knowledge/datasets/{active}/schema.md and quirks.md; connect with from helpers.data.connection_manager import ConnectionManager (or the local DuckDB/CSV fallback in the dataset manifest's local_data if no warehouse is reachable).
• An instruction to log its queries the way the repo expects.

Do NOT put Claude's SQL, result numbers, or conclusion in brief.md. That blindness is the whole point — it's what makes Codex's derivation independent.

Separately, stash Claude's original result in claude_original.md in the same run dir (headline number(s), SQL, conclusion). This file is for the Step 5 comparison only — it is not given to Codex.

Step 4 — Run Codex independently

Dispatch the codex:codex-rescue subagent (Agent tool) with brief.md and this output contract:

Independently answer the analytics question in this brief against the active dataset. Connect to the data and write your own SQL — do not ask for or assume anyone else's queries or numbers. Use the metric definition exactly as given. Log your queries. Then report ONLY:

• headline: <the single number you'd report> (one per finding if multiple)
• sql: <the query/queries you actually ran>
• measured: <numerator, denominator, grain, window, filters>
• conclusion: <one or two sentences>

Capture Codex's full response to codex_independent.md in the run dir.

(Fallback: if the subagent's output is unreliable or unavailable, run codex exec via Bash with the same brief and output contract, and save the result to the same file.)