workflows:review

Files (2)

• SKILL.md
• project-config.md · references/

SKILL.md (first lines)

# Review Command

**Pipeline mode:** This command operates fully autonomously. All decisions are made automatically.

Perform exhaustive econometric and methodological review using multi-agent parallel analysis. Domain-specific reviewers check estimation quality, identification strategy, numerical stability, and mathematical rigor.

## Input

<review_target> #$ARGUMENTS </review_target>

## Execution Workflow

### Phase 1: Scope Detection

0. **Eligibility Check**

   Before launching review agents, verify there is something to review. If no research artifacts are found (no estimation code, no proofs, no pipeline files, no data scripts, no output files), state "No research artifacts found to review" and stop. Do not launch agents against an empty target.

1. **Determine Review Target**

   The review is artifact-centric: it reviews research files (estimation code, proofs, pipelines, data scripts), not git metadata. Determine the target in priority order:

   - **File paths or directories** (e.g., `estimation.py`, `src/models/`, `proof.tex`) → review those artifacts directly
   - **Plan reference** (e.g., `plan-3`) → find the plan in `docs/plans/`, review files it references
   - **PR number** → fetch file list with `gh pr view --json files`
   - **Empty** → auto-detect: scan the project for estimation code, proofs, pipeline files, and data scripts. If git shows recent changes, include those.

2. **Classify Artifacts**

   Scan the target files and classify by type:

   ```
   estimation_code: *.py with statsmodels/scipy.optimize/pyblp/linearmodels imports
                    *.R with fixest/lfe/AER/gmm imports
                    *.jl with Optim/NLsolve imports
                    *.do with reg/ivregress/gmm commands
   simulation_code: Monte Carlo loops, DGP code, bias/RMSE computation
   proofs:          *.tex with theorem/proof environments, *.md with derivation sections
   pipeline_files:  Makefile, Snakefile, dvc.yaml, master.do
   data_code:       data loading, cleaning, merge operations
   output_files:    tables/*, figures/*, *.csv result files
   ```

   This classification drives which domain reviewers to launch.

3. **Load Review Settings**

   Read `compound-science.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context (e.g., "focus on identification strategy" or "this is a replication package"), pass it to each agent as additional instructions.

   If no settings file exists, use defaults:
   ```yaml
   review_agents:
     - econometric-reviewer
     - numerical-auditor
     - identification-critic
   ```

#### Protected Artifacts

The following paths are compound-science pipeline artifacts and must never be flagged for deletion or removal by any review agent:

- `docs/plans/*.md` — Plan files created by `/workflows:plan`
- `docs/brainstorms/*.md` — Brainstorm files created by `/workflows:brainstorm`
- `docs/solutions/*.md` — Solution documents created by `/workflows:compound`
- `docs/simulations/*.md` — Simulation study documentation

If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis.

### Phase 2: Agent Dispatch

**Entry condition:** Phase 1 classified at least one artifact; review settings loaded.
**Exit condition:** All dispatched agents have returned findings.

Launch domain reviewers in parallel using the Task tool. The specific agents depend on artifact classification from Phase 1.

#### Always Run (Core Domain Review)

<parallel_tasks>

Launch `econometric-reviewer`, `numerical-auditor`, and `identification-critic` in parallel:

```
Task econometric-reviewer(changed files + review context)
  → Checks: identification strategy, endogeneity, standard errors, instrument validity,
    sample selection, asymptotic properties, correct package usage

Task numerical-auditor(changed files + review context)
  → Checks: floating-point stability, convergence diagnostics, integration accuracy,
    RNG seeding, matrix conditioning, overflow/underflow, gradient accuracy

Task identification-critic(changed files + review context)
  → Checks: completeness of identification argument, exclusion restriction plausibility,
    functional form assumptions, parametric vs nonparametric claims, support conditions,
    point vs set identification
```

</parallel_tasks>

#### Conditional Agents (Run Based on Artifact Types)

<conditional_agents>

**WRITTEN ARTIFACTS: If PR contains proofs, derivations, or paper sections:**
(Files matching: `*.tex`, `*.md` with theorem/proof/lemma/proposition content, `docs/proofs/*`)

```
Task journal-referee(written artifact files + review context)
  → Simulates top-5 journal referee: contribution clarity, relation to literature,
    identification concerns, economic vs statistical significance, R&R concerns
    (robustness, external validity, mechanism)
```

**PIPELINE/DATA CODE: If PR contains pipeline files or data processing:**
(Files matching: `Makefile`, `Snakefile`, `dvc.yaml`, `*.do`, data loading/cleaning code)

```
Task reproducibility-auditor(pipeline files + review context)
  → Checks: intermediate files generated by code (no manual steps), seeds documented,
    package versions pinned, end-to-end pipeline, relative paths, data not committed

From James-Traina/compound-science, MIT.