Draft Review

Draft Review Skill

Review an academic draft rigorously and report issues by severity.

Inputs

• Primary document path: PDF, TeX, Markdown, or plain text
• Optional code path when the user wants code-paper consistency checks
• Optional scope override: comprehensive, mathematical, writing, quick-proof
• Optional thoroughness override: quick, standard, deep

If the user does not specify scope or thoroughness, use:

• Scope: comprehensive
• Thoroughness: standard

If the paper path or review target is ambiguous, ask the user a direct plain-language question before proceeding.

Review Workflow

Phase 1: Document Ingestion

1. PDF input

• Prefer converting the PDF to Markdown with the mistral-pdf-to-markdown skill if it is available.
• If that skill is not installed, extract text locally or ask the user for a TeX/Markdown source when equation fidelity matters.

2. TeX/Markdown input

• Read the source directly. Prefer TeX when mathematical precision matters.

3. Code input (optional)

• If the user supplied a code path, identify only the files needed to verify claims, definitions, tables, figures, and empirical procedures.

After ingestion, create a compact document summary:

• Paper title and abstract
• Section structure with approximate lengths
• List of figures and tables with captions
• Key notation/variable definitions index

Phase 2: Review Configuration

Use explicit user instructions when present. Otherwise:

• comprehensive: math, writing, consistency, argumentation, proofreading, citations, and optional code-paper consistency
• mathematical: derivations, equations, proofs, notation
• writing: clarity, structure, terminology
• quick-proof: typos, grammar, formatting

Thoroughness levels:

• quick: surface pass focused on highest-probability issues
• standard: one careful pass per relevant category
• deep: parallel or repeated review for maximum coverage

Phase 3: Optional Agent Delegation

Deep review is optional. Only use multi-agent delegation when all of the following are true:

• the user explicitly asked for deep, parallel, or multi-agent review, or approved delegation after you proposed it
• the current Codex session supports multi-agent work
• the extra review cost is justified by the document complexity

When available, prefer the standalone reviewer roles installed by scripts/install_codex_skills.py. Their agent_type values are:

If those installed roles are not present, either:

• perform the review inline in the main thread, or
• if the user explicitly requested deep parallel review, spawn generic worker agents with category-specific prompts

Never rely on the old plugin:agent role syntax.

Phase 4: Deep Mode Strategy

When thoroughness is deep, use one of these approaches:

1. Installed-role parallel review

• Spawn one reviewer per relevant category.
• For especially important categories, use two complementary perspectives.

2. Generic-worker parallel review

• Only if installed roles are unavailable and the user still wants parallel review.
• Give each worker a narrowly scoped prompt and a clear output contract.

3. Inline fallback

• If multi-agent delegation is unavailable, do the same review categories yourself in sequence.

Useful perspective variations:

• Reviewer A: skeptical referee looking for flaws
• Reviewer B: constructive mentor suggesting improvements
• Reviewer C: domain specialist focusing on the method that matters most

Useful traversal variations:

• Start from beginning and work forward
• Start from conclusions and trace claims backward
• Start from the most technical section first

After any delegated runs, merge findings:

• Deduplicate overlapping issues
• Mark issues found by multiple reviewers as higher confidence
• Keep unique findings that may catch edge cases

Phase 5: Result Aggregation

Collect all findings and organize by severity:

Critical (Priority 1):

• Mathematical errors in proofs or derivations
• Contradictory claims
• Missing critical references
• Data inconsistencies affecting results

Major (Priority 2):

• Logical gaps in argumentation
• Unclear methodology descriptions
• Significant notation inconsistencies
• Writing clarity issues affecting comprehension

Minor (Priority 3):

• Typos and grammatical errors
• Minor formatting issues
• Small notation inconsistencies
• Reference format issues

Phase 6: Actionable Follow-up

If the user wants a follow-up plan, provide a plain Markdown checklist grouped by severity instead of assuming a task-management tool exists.

Example:

## Action Items
- [ ] Fix Equation (14) sign error in Appendix A
- [ ] Define `kappa_t` on first use in Section 2
- [ ] Rephrase paragraph 3 on page 9 for clarity

Scope to Reviewer Mapping

*Only if a code path was provided

Optional spawn_agent Template

If you use installed reviewer roles, pass focused context instead of the entire document:

agent_type: draft-reviewer__mathematical-reviewer
message:
  Review the attached paper sections for mathematical correctness.

  Document summary:
  [title, abstract, section map]

  Sections to review:
  [only the relevant sections]

  Cross-reference index:
  [notation, tables, figures]

  Output format:
  ### [SEVERITY] [Category]: [Brief Title]
  **Location:** [Section/equation/page]
  **Issue:** [Description]
  **Recommendation:** [Suggested fix]
  **Auto-fixable:** [Yes/No]

Output Format

Final report structure:

# Draft Review Report: [Paper Title]

## Summary
- Total issues found: X
- Critical: X | Major: X | Minor: X
- Review scope: [scope]
- Thoroughness: [level]

## Critical Issues
[List with full details and recommendations]

## Major Issues
[List with details and suggestions]

## Minor Issues
[List with specific corrections]

## Auto-Fixable Items
[List of items that can be addressed quickly]

Dependencies

• Optional: mistral-pdf-to-markdown skill for higher-quality PDF ingestion
• Optional: advanced installer roles created by scripts/install_codex_skills.py

Issue Reporting Templates

Standardized formats for reporting review findings.

Issue Report Format

Each issue should be reported using this structure:

### [SEVERITY] [Category]: [Brief Title]

**Location:** [Section/Page/Equation/Table reference]

**Issue:** [Clear description of the problem]

**Evidence:** [Quote or reference to specific text/equation]

**Suggestion:** [Recommended fix or improvement]

**Auto-fixable:** [Yes/No]

Severity Levels

Critical (Priority 1)

Issues that invalidate results or major claims.

Indicators:

• Mathematical errors that change conclusions
• Data inconsistencies affecting key results
• Contradictory claims about main findings
• Missing critical methodological details

Example:

### CRITICAL Mathematical: Sign Error in Main Derivation

**Location:** Appendix A, Equation (A.3)

**Issue:** The derivative of the utility function has incorrect sign, which propagates to the main theoretical result.

**Evidence:**
- Eq (A.2): U = -exp(-γW)
- Eq (A.3) claims: dU/dW = exp(-γW)
- Correct: dU/dW = γ·exp(-γW)

**Suggestion:** Correct the derivative and verify all subsequent equations that depend on this result.

**Auto-fixable:** No

Major (Priority 2)

Issues that affect comprehension or require significant revision.

Indicators:

• Logical gaps in argumentation
• Unclear methodology affecting reproducibility
• Significant notation inconsistencies
• Writing issues that impede understanding

Example:

### MAJOR Clarity: Identification Strategy Unclear

**Location:** Section 3.2, paragraphs 2-4

**Issue:** The instrumental variable strategy is introduced but the exclusion restriction is never explicitly stated or justified.

**Evidence:** "We instrument X with Z" (p. 12) but no discussion of why Z affects Y only through X.

**Suggestion:** Add explicit statement of exclusion restriction and provide economic justification for why Z satisfies it.

**Auto-fixable:** No

Minor (Priority 3)

Issues that are small and often auto-fixable.

Indicators:

• Typos and grammatical errors
• Minor formatting inconsistencies
• Small notation inconsistencies
• Reference format issues

Example:

### MINOR Typo: Misspelling

**Location:** Section 4.1, paragraph 3, line 2

**Issue:** "heteroskedasticity" misspelled as "heteroskedastisity"

**Evidence:** "...robust to heteroskedastisity..."

**Suggestion:** Change to "heteroskedasticity"

**Auto-fixable:** Yes

Category-Specific Templates

Mathematical Issues

### [SEVERITY] Mathematical: [Title]

**Location:** [Equation number or section]

**Issue:** [Description of mathematical error]

**Current:** [What the paper says]
**Correct:** [What it should be]

**Verification Method:** [How you verified - symbolic/numerical]

**Impact:** [What results/claims are affected]

**Auto-fixable:** [Yes only for trivial notation fixes]

Writing/Clarity Issues

### [SEVERITY] Clarity: [Title]

**Location:** [Section, paragraph, or page]

**Issue:** [Description of clarity problem]

**Current text:** "[Problematic sentence or passage]"

**Suggested revision:** "[Improved version]"

**Reason:** [Why the change improves clarity]

**Auto-fixable:** [Yes for minor rewording, No for substantial revision]

Consistency Issues

### [SEVERITY] Consistency: [Title]

**Location A:** [First location]
**Location B:** [Second location with conflict]

**Issue:** [Description of inconsistency]

**At Location A:** [What it says/shows]
**At Location B:** [What it says/shows]

**Resolution:** [Which is correct, or how to reconcile]

**Auto-fixable:** [Yes if simple number fix]

Citation Issues

### [SEVERITY] Citation: [Title]

**Location:** [Where citation appears or should appear]

**Issue:** [Description of citation problem]

**Current:** [Current state]
**Suggested:** [Correction]

**Auto-fixable:** [Yes for format fixes, No for missing citations]

Code-Paper Consistency Issues

### [SEVERITY] Code-Paper: [Title]

**Paper Location:** [Section/equation in paper]
**Code Location:** [File:line in code]

**Issue:** [Description of discrepancy]

**Paper says:** [Paper description]
**Code does:** [Code behavior]

**Resolution:** [Which is correct and what needs updating]

**Auto-fixable:** No (requires author decision)

Aggregated Report Template

# Draft Review Report

**Paper:** [Title]
**Date:** [Review date]
**Scope:** [Review scope selected]
**Thoroughness:** [Level selected]

## Executive Summary

| Severity | Count | Auto-fixable |
|----------|-------|--------------|
| Critical | X     | 0            |
| Major    | Y     | 0            |
| Minor    | Z     | N            |
| **Total**| **T** | **N**        |

### Top Priorities
1. [Most critical issue - one line summary]
2. [Second most critical]
3. [Third most critical]

---

## Critical Issues

[List all critical issues using templates above]

---

## Major Issues

[List all major issues using templates above]

---

## Minor Issues

[List all minor issues using templates above]

---

## Auto-Fixable Items Summary

For user approval before task creation:

| # | Location | Issue | Fix |
|---|----------|-------|-----|
| 1 | p.5, ¶2  | Typo  | "teh" → "the" |
| 2 | Eq (3)   | Notation | "α" → "β" (consistency) |
| ... | ... | ... | ... |

---

## Review Coverage

### Sections Reviewed
- [x] Abstract
- [x] Introduction
- [x] Section 2: [Title]
- ...

### Agents Used
- [x] Mathematical Reviewer
- [x] Writing Clarity Reviewer
- ...

### Limitations
- [Any sections not reviewed or limitations of the review]

Task Creation Format

When creating tasks for auto-fixable issues (after user permission):

Subject: Fix [issue type] in [location]

Description:
- Location: [precise location]
- Current: [current text/equation]
- Change to: [corrected version]
- Reason: [brief explanation]

Source: Draft Review - [timestamp]

Review Categories Reference

Detailed criteria for each review category.

1. Mathematical Review

Scope

• Derivations and proofs
• Equations and algebra
• Notation consistency
• Statistical/econometric specifications

Verification Methods

Symbolic Verification:

• Check each algebraic step in derivations
• Verify equation transformations
• Confirm limit taking and approximations

Numerical Verification:

• For complex derivations, test with concrete values
• Check boundary conditions (e.g., when parameter → 0 or → ∞)
• Verify dimension/unit consistency

Notation Consistency:

• Same variable should have same meaning throughout
• Check for redefinitions without clear notice
• Verify subscript/superscript conventions are consistent

Common Issues to Check

• Sign errors in derivatives
• Incorrect application of chain rule
• Missing terms in Taylor expansions
• Incorrect matrix algebra (transpose, inverse)
• Statistical distribution misspecifications
• Incorrect asymptotic approximations

2. Writing Clarity Review

Scope

• Sentence structure and readability
• Paragraph organization
• Terminology consistency
• Definition clarity

Clarity Criteria

Sentence Level:

• Avoid overly long sentences (>40 words)
• Subject-verb agreement
• Clear referents for pronouns
• Active voice preferred for key claims

Paragraph Level:

• Topic sentence present
• Logical flow between sentences
• One main idea per paragraph
• Transitions between paragraphs

Terminology:

• Key terms defined before use
• Consistent terminology throughout
• No conflicting definitions
• Technical terms explained for intended audience

Common Issues to Check

• Ambiguous "this" or "it" references
• Passive voice obscuring who does what
• Jargon without explanation
• Inconsistent term usage (e.g., "effect" vs "impact" for same concept)
• Circular definitions

3. Consistency Check

Scope

• Numbers across tables and text
• Figure/table references
• Claims match evidence
• Cross-section consistency

What to Compare

Tables:

• Numbers in text match table values
• Table notes consistent with methodology
• Column/row labels clear and consistent

Figures:

• Figure captions match content
• Axis labels consistent with text notation
• Legend items all explained

Claims:

• Quantitative claims traceable to tables/figures
• Qualitative claims supported by evidence
• No contradictory statements

Common Issues to Check

• Rounding inconsistencies between text and tables
• Wrong table/figure referenced
• "Significant" claims not matching p-values
• Sample sizes inconsistent across tables
• Time periods/variable definitions drift

4. Argument & Logic Review

Scope

• Logical flow of arguments
• Claim support and evidence
• Identification strategy validity
• Causal claims appropriateness

Argumentation Criteria

Claim Support:

• Each major claim has supporting evidence
• Evidence type matches claim type
• Magnitude of claims proportional to evidence

Logical Flow:

• Introduction sets up research question clearly
• Methodology justifies approach taken
• Results follow from methodology
• Conclusions follow from results

Causal Reasoning:

• Causal claims have valid identification
• Correlation vs causation distinguished
• Alternative explanations addressed
• Robustness of causal claims tested

Common Issues to Check

• Overclaiming (strong claims from weak evidence)
• Missing logical steps
• Unaddressed alternative explanations
• Circular reasoning
• Post-hoc rationalization of results

5. Proofreading

Scope

• Spelling and typos
• Grammar and punctuation
• Formatting consistency
• LaTeX/rendering issues

Proofreading Checklist

Spelling/Typos:

• Common homophone errors (their/there, its/it's)
• Double words
• Missing words
• Proper nouns spelled correctly

Grammar:

• Subject-verb agreement
• Tense consistency
• Article usage (a/an/the)
• Comma usage

Formatting:

• Consistent heading styles
• Consistent number formatting (1,000 vs 1000)
• Consistent date formats
• Table/figure numbering sequential
• Consistent font/spacing

LaTeX-Specific:

• Missing closing braces
• Equation numbering gaps
• Broken cross-references
• Missing bibliography entries
• Overfull/underfull hbox warnings

Common Issues to Check

• Capitalization inconsistency
• Hyphenation inconsistency
• Citation format inconsistency
• Footnote/endnote format inconsistency

6. Citation Check

Scope

• Citation completeness
• Reference format
• Citation-reference matching
• Key literature coverage

Citation Criteria

Completeness:

• All claims have appropriate citations
• Classic/foundational papers cited
• Recent relevant literature included
• No "orphan" citations (cited but not in bibliography)
• No "orphan" references (in bibliography but not cited)

Format:

• Consistent citation style (APA, Chicago, etc.)
• All required fields present (author, year, title, journal)
• DOIs/URLs functional and correctly formatted
• Page numbers included for direct quotes

Appropriateness:

• Citations support the claims they're attached to
• Not over-citing or under-citing
• Self-citation appropriate (not excessive)

Common Issues to Check

• Author name spelling variations
• Year discrepancies
• Journal name abbreviation inconsistency
• Missing working paper version updates
• Broken URLs

7. Code-Paper Consistency

Scope

• Methodology description matches implementation
• Variable definitions match code
• Sample construction reproducible
• Results replicable from code

Consistency Criteria

Methodology:

• Equations in paper match code implementation
• Sample restrictions described match code
• Variable transformations documented

Variables:

• Variable names/descriptions traceable to data/code
• Missing value handling consistent
• Winsorization/trimming as described

Results:

• Key statistics reproducible
• Robustness checks implemented as described
• Figures generated from provided code

Common Issues to Check

• Undocumented sample restrictions in code
• Different default values than stated
• Outdated code not matching final paper
• Hard-coded values that should be parameters
• Missing intermediate data processing steps