research-review skill

Override for Codex users who want Claude Code, not a second Codex agent, to act as the reviewer. Install this package after skills/skills-codex/*.

This reviewer is a different model family from the Codex executor. Every overlay trace/audit records:

yaml

review_independence: cross-family

acceptance_status: accepted

Research Review via claude-review MCP (high-rigor review)

Claude overlay assurance: this route is a different model family from the Codex executor and records reviewindependence: cross-family plus acceptancestatus: accepted.

Get a multi-round critical review of research work from an external LLM with maximum reasoning depth.

Constants

• REVIEWERMODEL = claude-review — Claude reviewer invoked through the local claude-review MCP bridge. Set CLAUDEREVIEW_MODEL if you need a specific Claude model override.
• REVIEWERBACKEND = claude-review** — reviews route through the claude-review MCP (Claude family; cross-family for a Codex executor).

Context: $ARGUMENTS

Prerequisites

• Install the base Codex-native skills first: copy skills/skills-codex/* into ~/.codex/skills/.
• Then install this overlay package: copy skills/skills-codex-claude-review/* into ~/.codex/skills/ and allow it to overwrite the same skill names.
• Register the local reviewer bridge:

codex mcp add claude-review -- python3 ~/.codex/mcp-servers/claude-review/server.py

• This gives Codex access to mcpclaude-reviewreviewstart, mcpclaude-reviewreviewreplystart, and mcpclaude-reviewreviewstatus.

Workflow

Step 1: Gather Research Context

Before calling the external reviewer, compile a comprehensive briefing:

1. Read project narrative documents (e.g., STORY.md, README.md, paper drafts)
2. Read any memory/notes files for key findings and experiment history
3. Identify: core claims, methodology, key results, known weaknesses

Step 2: Initial Review (Round 1)

Send a detailed prompt with ultra reasoning:

mcp__claude-review__review_start:
  prompt: |
    [Full research context + specific questions]
    Please act as a senior ML reviewer (NeurIPS/ICML level). Start from the
    assumption that the work is broken somewhere — your job is to find where.
    Be adversarial. Trust nothing the author tells you — verify everything
    yourself. Identify:
    1. Logical gaps or unjustified claims
    2. Missing experiments that would strengthen the story
    3. Narrative weaknesses
    4. Whether the contribution is sufficient for a top venue

    === SCOPE LIMITS (these bound what you PROPOSE, never what you look for) ===
    Report anything that is actually wrong here — including a rare-looking case, if
    this repo actually produces it. Then keep the fix in scope:
    1. This is a RESEARCH-WORKFLOW tool, not a security paper. Verification is
       welcome; over-defense is not. Assume a cooperating operator on their own
       machine — a malicious local user is NOT in the threat model.
    2. Do NOT propose SHA / hash / content-fingerprint / digest-binding schemes.
       Reporting a real defect in hashing code that already exists is fine.
    3. NO speculative machinery: do not add fea

After this start call, immediately save the returned jobId and poll mcpclaude-reviewreview_status with a bounded waitSeconds until done=true. Treat the completed status payload's response as the reviewer output, and save the completed threadId for any follow-up round.

Step 3: Iterative Dialogue (Rounds 2-N)

Use mcpclaude-reviewreviewreplystart with the saved completed threadId, then poll mcpclaude-reviewreview_status with the returned jobId until done=true to continue the conversation:

mcp__claude-review__review_reply_start:
  # the bridge grants the reviewer no tools by default; this prompt passes
  # artifact paths, so it has to ask for read-only access explicitly
  tools: "Read,Grep,Glob"
  threadId: [saved reviewer id from Step 2]
  prompt: |
    Please continue the review using the revised materials below.

    Revised files:
    - /absolute/path/to/file1
    - /absolute/path/to/file2

    Focus on unresolved weaknesses and whether the revision actually fixed them.

After this start call, immediately save the returned jobId and poll mcpclaude-reviewreview_status with a bounded waitSeconds until done=true. Treat the completed status payload's response as the reviewer output, and save the completed threadId for any follow-up round.

For each round:

1. Respond to criticisms with evidence/counterarguments
2. Ask targeted follow-ups on the most actionable points
3. Request specific deliverables: experiment designs, paper outlines, claims matrices

Key follow-up patterns:

• "If we reframe X as Y, does that change your assessment?"
• "What's the minimum experiment to satisfy concern Z?"
• "Please design the minimal additional experiment package (highest acceptance lift per GPU week)"
• "Please write a mock NeurIPS/ICML review with scores"
• "Give me a results-to-claims matrix for possible experimental outcomes"

Step 4: Convergence

Stop iterating when:

• Both sides agree on the core claims and their evidence requirements
• A concrete experiment plan is established
• The narrative structure is settled

Step 5: Document Everything

Save the full interaction and conclusions to a review document in the project root:

• Round-by-round summary of criticisms and responses
• Final consensus on claims, narrative, and experiments
• Claims matrix (what claims are allowed under each possible outcome)
• Prioritized TODO list with estimated compute costs
• Paper outline if discussed

Update project memory/notes with key review conclusions.

If — composed: is explicitly present, fold consensus, claims matrix, TODOs, and trace links into that report instead of writing a standalone review document. Without the directive, write the standalone review as documented; never infer composed mode from an existing file. — standalone always wins. See output-composition.md.

Step 6: Review Tracing

Save a trace for every mcpclaude-reviewreviewstart, mcpclaude-reviewreviewreply_start, or oracle-pro review call following ../shared-references/review-tracing.md. Record the reviewer route, saved threadId, prompt summary, raw response path, decisions, and action items. This preserves the Claude mainline Review Tracing semantics while using Codex-native reviewer calls.

Key Rules

• Always ask the Claude reviewer for strict, high-rigor feedback in every review round.
• Send comprehensive context in Round 1 — the external model cannot read your files
• Be honest about weaknesses — hiding them leads to worse feedback
• Push back on criticisms you disagree with, but accept valid ones
• Focus on ACTIONABLE feedback — "what experiment would fix this?"
• Document the completed threadId for potential future resumption
• The review document should be self-contained (readable without the conversation)

Prompt Templates

For initial review:

"I'm going to present a complete ML research project for your critical review. Please act as a senior ML reviewer (NeurIPS/ICML level)..."

For experiment design:

"Please design the minimal additional experiment package that gives the highest acceptance lift per GPU week. Our compute: [describe]. Be very specific about configurations."

For paper structure:

"Please turn this into a concrete paper outline with section-by-section claims and figure plan."

For claims matrix:

"Please give me a results-to-claims matrix: what claim is allowed under each possible outcome of experiments X and Y?"

For mock review:

"Please write a mock NeurIPS review with: Summary, Strengths, Weaknesses, Questions for Authors, Score, Confidence, and What Would Move Toward Accept."