# Reviewer Guide

Read article drafts, verify the claims against the underlying tool data, file structured feedback. For the step-by-step "open Claude, do this" sequence, see [`WORKFLOW.md#c-review-an-existing-article`](WORKFLOW.md#c-review-an-existing-article).

**Two ways to use this guide**:
- **Copy-paste prompts** (below) — works in any Claude surface (claude.ai chat, Claude Code, Cursor)
- **Claude Code skills** — `/review-article` chains R1+R2+R3 into one session and writes the feedback file for you. If you spot a methodology-level pattern across multiple articles you're reviewing (vs. an issue with one article), run `/methodology-feedback` after. See [`.claude/skills/README.md`](.claude/skills/README.md).

## Quick-start Claude prompts (copy-paste ready)

Open Claude (claude.ai chat, Claude Code CLI, or Cursor / VS Code with Claude integration). Edit the `<placeholders>` and paste.

### Prompt R1 — First-pass claim trace

```
I'm reviewing an article at <article-folder> (e.g. ad-hoc/articles/seidman-easy-game-reexamined/ or da-pipeline/hand-1011-31/).

Read:
  - The prose file (v1.md for ad-hoc; the per-format .md for da-pipeline)
  - Every *.json file in the same folder (solver outputs)
  - Any prior feedback at <article-folder>/_review/feedback_*.md

For every solver / equity / range / frequency claim in the prose, give me:
  1. The claim text verbatim (quoted)
  2. The matching value in the JSON (file + path)
  3. Verdict: correct | wrong | ambiguous
  4. Severity: P0 (wrong strategy, blocks ship) | P1 (wrong value, must fix) | P2 (nit)

Output as a markdown table I can paste into a feedback file.

Also flag:
  - Any claim you can't find a JSON source for (these are LLM hallucinations the writer didn't catch)
  - Any hedge words ("clearly", "obviously", "of course", "naturally")
  - Any specific EV numbers in prose (qualitative only allowed)
  - Any inconsistent suit symbols
```

### Prompt R2 — Strategic + editorial pass

After R1's claim trace, get a higher-level critique.

```
You read <article-folder>/<prose-file>. Now give me a strategic + editorial review:

1. Strategic correctness — does the recommendation make sense given the data in the JSON? Any obvious exploits or context the article misses?
2. Hook — does the opening grab attention? If not, propose 2 alternatives.
3. Structure — does the section order match the type's methodology pattern (see ad-hoc/methodology/types/<type>.md for ad-hoc; da-pipeline/_template/<format>.md for DA)?
4. Voice — does the prose feel like a coach talking, or like an LLM checklist?
5. Common mistakes section — generic or specific to a real player population?

Be direct and specific. Cite section + line as you go.
```

### Prompt R3 — Draft the feedback file

After R1 + R2, generate the final feedback file.

```
Based on your R1 claim trace and R2 strategic notes, draft a complete feedback file for me to save at <article-folder>/_review/feedback_<my-name>.md.

Use the template at the bottom of REVIEWER_GUIDE.md verbatim — keep all headings and field names exactly as written. Fill in:
  - Reviewer / Date / Article folder / Format / Time spent
  - Overall verdict + one-line summary
  - Per-claim review table (from R1)
  - Strategic / editorial notes (from R2)
  - Style / voice notes
  - Suggested prompt / format change (if you saw a recurring pattern, not just this article)
  - Anything else

After I save the file, I'll commit + PR per WORKFLOW.md section C.
```

---

## What to review

Articles ready for review have a `_review/` subfolder. Read:

- The prose (`v1.md` for ad-hoc; `core_da.md` / `five_section.md` / etc. for DA-pipeline)
- The supporting data (`tool_trace.json`, `hygiene_check.md`, `verifier_results.md`, per-hand `*.json`)
- Prior reviewer feedback (`_review/feedback_<other>.md`)

You're reviewing the *output*, not the *engine* — pipeline internals don't live in this repo by design.

## What to check

| Layer | What you're looking for |
|---|---|
| **Claim accuracy** | For every solver/equity/range/frequency claim, find the matching value in tool data. If not, flag it. |
| **Numerical hygiene** | Numbers match canonical references. `hygiene_check.md` PASS (DA-pipeline); for ad-hoc, numbers traced back to pulled JSON. |
| **Strategic correctness** | Recommendation makes sense given the data? Obvious exploits or context missed? |
| **Voice + clarity** | On-brand, free of overhyped language and AI tics? Structure matches the format? |
| **LLM tells** | Hedge words ("clearly", "obviously"), specific EV numbers, fabricated nut-rankings, wrong-side recommendations. |

## You can't edit prompts — and that's fine

External reviewers don't have access to underlying prompts or pipeline code. Your job is **signal**; the internal team owns prompt edits.

- **DA pipeline**: methodology changes go through Harold + Chris (CAI team) via the "Suggested Prompt / Format Change" field below.
- **Ad-hoc**: Thanh owns methodology. Writers may edit it directly (per [`WORKFLOW.md#d-update-methodology`](WORKFLOW.md#d-update-methodology)); reviewer suggestions still route through Thanh.

## Where feedback routes

- **DA-pipeline reviews** → Harold reads first, may escalate to Chris/CAI engineering
- **Ad-hoc reviews** → Thanh reads first

Cadence: aim for feedback within **3-5 days** of taking on an article. If you can't, drop a note in the PR so we can reassign.

## Reviewer feedback template — copy into the article's `_review/` folder

Save as `<article-folder>/_review/feedback_<your-name>.md`. Keep headings + field names exactly.

```markdown
# Feedback — <article-folder> — <your-name>

**Reviewer**: <your-name-or-handle>
**Date**: <YYYY-MM-DD>
**Article folder**: <e.g. da-pipeline/hand-1011-31/ or ad-hoc/articles/seidman-easy-game-reexamined/>
**Format(s) reviewed**: <e.g. V2 Five-Section | mechanism-walkthrough>
**Time spent**: <e.g. 45 min>

---

## Overall verdict

**Verdict**: <accept-as-is | accept-with-edits | needs-rework | reject>
**One-line summary**: <single sentence on the headline issue or "ready to ship">

---

## Per-claim review

| # | Claim text (paraphrased) | Verdict | Severity | Notes |
|---|---|---|---|---|
| 1 | <e.g. "Hero raises to 4.8bb 94% of the time"> | correct | wrong | ambiguous | P0 | P1 | P2 | <what should change> |

**Verdict**: `correct` = matches data; `wrong` = contradicts data; `ambiguous` = judgment call
**Severity**: `P0` = wrong strategy, blocks publication · `P1` = wrong value, requires correction · `P2` = nit, can ship

---

## Strategic / editorial notes

<Free-form. Missing exploit angles, unclear sections, hook tweaks, common-mistake refinements.>

---

## Style / voice notes

<Voice issues, AI tells, hedge words, inconsistencies.>

---

## Suggested Prompt / Format Change (optional)

If this article reveals a pattern that should change at the prompt or format level:

**Affected variant**: <e.g. V2 Five-Section>
**Pattern observed**: <recurring issue across multiple articles>
**Proposed change**: <what should the prompt or format do differently>
**Why**: <reason>

---

## Anything else

<Open thoughts, questions, things that didn't fit a structured field.>
```

## Need help?

- Process questions → ping your track owner (Harold+Chris or Thanh)
- "Is this a known issue?" → check existing `_review/feedback_*.md` files first
- Technical questions about how tool data is generated → track owner