ds-review

What this skill does

Announce: "Using ds-review (Phase 4) to check methodology and quality."

## Context Monitoring

| Level | Remaining Context | Action |
|-------|------------------|--------|
| Normal | >35% | Proceed normally |
| Warning | 25-35% | Complete current review cycle, then trigger ds-handoff |
| Critical | ≤25% | Immediately trigger ds-handoff — do not start new review cycles |

## Review Strategy Choice

After announcing phase, choose review strategy.

**Skip this choice when:**
- Exploratory analysis (one-off, not for publication)
- Trivial changes (formatting, documentation)
- Internal reporting (low-stakes, quick turnaround)
- Single notebook with < 100 LOC

**Otherwise, ask the user:**

```python
AskUserQuestion(questions=[{
  "question": "How should we review this analysis?",
  "header": "Review Strategy",
  "options": [
    {"label": "Single reviewer (Default)", "description": "Combined review covering methodology, data quality, and reproducibility. Faster, lower overhead."},
    {"label": "Parallel review (Research-grade)", "description": "Spawn 3 specialized reviewers (Methodology, Reproducibility, Code quality). Use for publications, high-stakes decisions, or research-grade work. Requires reconciliation."}
  ],
  "multiSelect": false
}])
```

**If Single reviewer:** Proceed to [The Iron Law of DS Review](#the-iron-law-of-ds-review) below (current behavior).

**If Parallel review:** Skip to [Parallel Review (Research-Grade)](#parallel-review-research-grade).

---

## Parallel Review (Research-Grade)

Use this section when user chose "Parallel review (Research-grade)" above.

> **Prerequisite:** Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` enabled. If unavailable, fall back to single reviewer.

### 1. Prerequisites Check

Before spawning reviewers, verify:

1. **`.planning/SPEC.md` exists** - reviewers verify against spec, not assumptions
2. **`.planning/PLAN.md` exists** - reviewers check tasks were completed
3. **`.planning/LEARNINGS.md` exists** - reviewers verify data quality pipeline documented
4. **Analysis files identified** - notebooks/scripts in scope for review

If any prerequisite fails, STOP and return to /ds-implement.

### 2. When to Use Parallel Review

**Use parallel review when:**
- Publication-bound work (papers, reports, external sharing)
- High-stakes decisions (business strategy, funding, policy)
- Research-grade analysis (academic standards, peer review)
- Regulatory compliance (audit trail required)
- Complex methodology (multiple statistical methods, model comparisons)
- Large codebases (4+ notebooks, multiple scripts)

**Do NOT use when:**
- Exploratory analysis (one-off, not for publication)
- Internal reporting (low-stakes, quick answers)
- Simple descriptive stats (counts, means, basic visualizations)
- Overhead exceeds benefit (single notebook, < 100 LOC)

### 3. Create Team and Spawn Reviewers

#### Team Creation

```
TeamCreate(name="Analysis Review", task_description="Parallel analysis review with 3 specialized reviewers")
```

Press **Shift+Tab** to enter delegate mode. The lead coordinates reviews, does NOT review analysis directly.

#### Spawn 3 Reviewers

Each reviewer receives a self-contained prompt from a reference file. **Reviewers start with a blank conversation and do NOT auto-load skills.** Read the prompt, substitute variables, and paste it in full.

**Tool Restrictions:** All reviewers (Methodology, Reproducibility, Code Quality) are READ-ONLY with `allowed_tools=["Read", "Glob", "Grep", "Bash(read-only)"]`. Reviewers read code and data, run verification checks, and return verdicts. They MUST NOT use Write or Edit.

**Before spawning, substitute these variables in each prompt:**
- `ANALYSIS_FILES` → list of notebooks/scripts in scope (paste actual list)
- `SPEC_CONTEXT` → relevant sections of .planning/SPEC.md (paste inline, do NOT reference file)
- `PLAN_TASKS` → task list from .planning/PLAN.md (paste inline, verify completed)
- `LEARNINGS_PIPELINE` → data quality chain from .planning/LEARNINGS.md (paste inline)
- `PLUGIN_ROOT` → resolved base directory for skill paths (relative to this skill's base directory)

**Reviewer prompts (read, substitute variables, send as message):**

| Reviewer | Focus | Prompt Source |
|----------|-------|---------------|
| 1. Methodology | Statistical soundness, assumptions, bias | `references/methodology-reviewer.md` |
| 2. Reproducibility | Seeds, versions, data traceability | `references/reproducibility-reviewer.md` |
| 3. Code Quality | Data quality handling, bugs, efficiency | `references/code-quality-reviewer.md` |

---

### 4. Lead Monitoring

While reviewers work, the lead:

- **Watches for completion messages** from all 3 reviewers
- **Does NOT review analysis directly** - your job is coordination and reconciliation
- **If a reviewer asks a question:** Answer it, then broadcast to other reviewers if relevant
- **If a reviewer is taking significantly longer than others:** Message them for status
- **When all 3 reviewers complete:** Proceed to reconciliation

### 5. Reconciliation Protocol (3 Passes)

After ALL reviewers message completion, the lead performs three passes.

**This flowchart IS the specification. If the prose below and this diagram disagree, the diagram wins.**

```
   3 reviewer findings sets (Methodology, Reproducibility, Code Quality)
                              │
                              ▼
        ┌─────────────────────────────────────────┐
        │ Pass 1 — DEDUPLICATE                     │
        │ group by file:location + root cause,     │
        │ merge dups (keep highest confidence)     │
        └───────────────────┬─────────────────────┘
                            ▼
        ┌─────────────────────────────────────────┐
        │ Pass 2 — PRIORITIZE                      │
        │ rank critical / important / minor        │
        └───────────────────┬─────────────────────┘
                            ▼
        ┌─────────────────────────────────────────┐
        │ Pass 3 — INTEGRATION CHECK               │
        │ do findings conflict / interact?         │
        └───────────────────┬─────────────────────┘
                  conflict?  │
            ┌──── yes ───────┴────── no ──────┐
            ▼                                  ▼
   ┌──────────────────┐         ┌──────────────────────────┐
   │ escalate to user │         │ any critical/important?   │
   │ with the conflict│         └────────────┬─────────────┘
   └──────────────────┘            ┌── yes ──┴── no ──┐
                                   ▼                  ▼
                          ┌────────────────┐ ┌────────────────┐
                          │ CHANGES REQ'D →│ │ APPROVED →     │
                          │ /ds-implement  │ │ ds-verify      │
                          │ (max 3 cycles) │ └────────────────┘
                          └────────────────┘
```

<EXTREMELY-IMPORTANT>
**Pass 1 — Deduplication:**

Multiple reviewers may find the same issue (e.g., missing seed found by both Reproducibility and Code Quality reviewers).

1. Read all reviewer findings
2. Group by file and location
3. Identify duplicates:
   - Same file:location
   - Same root cause (even if described differently)
4. Merge duplicates:
   - Keep the highest confidence score
   - Combine descriptions if both add value
   - Attribute to both reviewers

**Example:**
```
Reproducibility found: "notebook.ipynb cell 5 - Random seed not set (Confidence: 85)"
Code Quality found: "notebook.ipynb cell 5 - Stochastic operation unseeded (Confidence: 80)"

→ Merge: "notebook.ipynb cell 5 - Random seed missing for train_test_split (Confidence: 85, found by Reproducibility + Code Quality)"
```

**Pass 2 — Prioritization:**

Not all issues are equally important. Rank by:

1. **Severity × Confidence:**
   - Critical (90-100 confidence) > Important (80-89)
   - Methodology > Reproducibility > Code Quality (when confidence is equal)
2. **Impact on conclusions:**
   - Invalidates results > Affects interpret