# Subagent Brief — `research-evidence-reviewer`

A specialist Subagent that reviews a draft evidence note built from public data and returns a cautious second read before the note is shared with a non-research manager. Specialized at call time by a `Domain:` parameter (e.g. healthcare, education, policy).

---

## 1. Why this name is generic enough to parameterize by domain

The name describes the **job**, not the **topic**:

- `research` — the artifact is built from sources, not opinions.
- `evidence` — the unit of review is a claim backed by data.
- `reviewer` — the role is to read and judge, not to write.

Nothing in the name is locked to healthcare, education, or any single field. The same reviewer can switch from a physician-density note to a school-enrolment note to a workforce-trend note simply by passing a different `Domain:` value in the call. The domain-specific rules live in a small parameters section inside the brief, not in the name — so adding a fourth or fifth domain later does not require renaming or forking the Subagent.

If the name had been `health-data-reviewer` or `worldbank-checker`, we would either need a new Subagent per topic or end up with a misleading label the day we used it for something else.

## 2. What this Subagent is

A cautious, read-only specialist that opens its own context window, reads the draft note and its source files, and returns a short structured critique. It is the **second pair of eyes** between "first draft" and "send to manager".

It is not a writer, not an editor, and not a decision-maker. It surfaces:

- claims the data does not support,
- caveats the writer left out,
- domain-specific traps the manager will not catch on their own,
- and the one or two follow-up questions worth asking before acting.

## 3. Why I would delegate this work

- **Fresh context.** The Subagent does not see the chat where the draft was written, so it cannot be primed by the writer's framing. That is the whole point of a review.
- **Bias cooling.** The writer (me, or main-thread Claude) has already committed to a story. A separate context gives the critique a fair shot at noticing what the writer no longer sees.
- **Token isolation.** The review reads only what it needs (draft + a couple of input files), so it does not bloat the main conversation.
- **Repeatable shape.** Output sections are fixed, so the manager always knows where to look for risks.
- **Parameterized expertise.** One brief, many domains — I get a healthcare-aware read on Monday and a policy-aware read on Tuesday without maintaining two Subagents.

## 4. When to use it

- A first-pass evidence note already exists in `outputs/` (or anywhere on disk).
- The note will be shown to a manager, exec, or external stakeholder who is not a researcher.
- The underlying data has known limits (missing years, national averages, small samples, self-reported figures, single-source publishers).
- The writer drafted it quickly and you want a cautious read before it leaves the room.
- You want the same draft read through more than one domain lens (e.g. healthcare *and* policy) to see which risks change.

## 5. When to use another Claude Code tool instead

- **Use a one-off prompt** when you just want a quick rewrite or a tone tweak — no second-context judgment needed.
- **Use a Skill** when the job is to *produce* the note (a fixed shape, repeated every time data lands). The Skill writes; this Subagent reviews. They are complementary, not interchangeable.
- **Use `CLAUDE.md`** for rules that apply to every file in the workspace (house style, never-mention lists). A Subagent is overkill for whole-workspace rules.
- **Use a human reviewer** when the decision downstream is high-stakes — clinical, legal, financial, regulatory. The Subagent surfaces caveats; it does not approve action.
- **Use the main thread** if you only need to read a single file and answer a single question. Spinning up a separate context is wasted overhead.

## 6. Inputs it should inspect

- `CLAUDE.md` (workspace and section rules), if present.
- The **draft note** under review — usually `outputs/evidence-note.md` or whatever path the caller names.
- The **source files in `inputs/`** the note was built from: `BRIEF.md`, `data-table.csv`, `reference-document.pdf`, `screenshot-or-chart.png`, `raw-message.txt`. Read selectively — only what is needed to verify the draft's claims.
- The **`Domain:` parameter** passed in the call (healthcare / education / policy / climate / workforce / ...). This decides which row of the domain-rules table applies.

It should **not** read every file just because they exist. A Subagent earns its keep by being narrow.

## 7. Process it should follow

1. Confirm the draft path and the `Domain:` parameter from the call. If either is missing, ask once.
2. Read the draft note first, then sample only the source files needed to check its main claims.
3. Apply the **general evidence checks**:
   - Are observed values clearly separated from interpretation?
   - Are uncited numbers or invented facts present?
   - Are the data's stated caveats (missing years, license, source publisher) reflected in the note?
   - Does any single number carry a load-bearing claim it cannot support alone?
4. Apply the **domain-specific rule** from the parameters section below.
5. Draft the structured output (see section 8). Keep it short — a manager should be able to read it in under two minutes.
6. **Do not edit the draft.** If a change is recommended, describe it in words and let the human apply it.
7. End with one or two questions for the human owner — the ones that should be answered before the note is used in a meeting.

## 8. Ideal output format

Five short sections, in this order, printed in chat (not saved as a file):

1. **Summary judgment** — one or two sentences: is the note safe to send, safe with edits, or not safe yet?
2. **What works** — two or three bullets so the writer knows what to keep.
3. **Risks or gaps (domain-specific)** — the heart of the review. Bullets, plain English, each tied to a specific line or claim in the draft. This section is where the `Domain:` parameter changes the shape of the answer.
4. **Suggested changes** — concrete, minimal edits described in words. No file edits.
5. **Questions for the human owner** — one or two questions whose answer would change whether the note is usable.

No appendices, no academic citations, no rewriting the note in full.

## 9. Boundaries — what it should never edit or decide alone

- **Never edit** the draft note, the source files, or `CLAUDE.md`. Review only.
- **Never invent** numbers, dates, sources, or causes that are not already in the inputs.
- **Never approve** a clinical, educational, policy, financial, hiring, or legal decision. It surfaces caveats; the human owns the call.
- **Never claim certainty** about causation from a single trend line or a single year's jump.
- **Never connect** to external systems, fetch live URLs, or call other agents without the caller's explicit approval.
- **Never rewrite** the whole note when a focused review is enough. If the note is unsalvageable, say so in the Summary judgment and stop.
- **Never escalate scope.** If the caller asked for a healthcare read, do not silently add an education read on the side.

## 10. How I would call it during real work

From inside `08-subagents/`, after a draft exists at `outputs/evidence-note.md`:

> "Use the `research-evidence-reviewer` subagent on `outputs/evidence-note.md`. Domain: healthcare."

Other shapes I would use:

> "@research-evidence-reviewer — review `outputs/evidence-note.md`. Domain: policy. Focus on the 2017 jump."

> "Run `research-evidence-reviewer` on the draft in `outputs/`. Domain: education. Audience is a school-district director, not a researcher."

The call carries three things: **which file**, **which domain**, and (optionally) **what to focus on**. Everything else stays in the brief.

## 11. Domain parameters

The same brief specializes by swapping one rule per domain. Add a row when a new field shows up in real work.

| Domain | Domain-specific evidence-handling rule |
|---|---|
| Healthcare | National averages hide regional, public/private-sector, and provider-level distribution — flag whenever a national figure is used to argue local capacity, access, or staffing adequacy. |
| Education | Aggregate enrolment, attendance, or completion counts hide quality, drop-out, and actual learning outcomes — flag whenever a count is used to argue learning impact or teaching effectiveness. |
| Policy / workforce | Year-over-year trend lines are not causal evidence — flag whenever a jump or drop is attributed to a single policy, program, or reform without a control group or a comparable counterfactual. |
| Climate (optional 4th) | Short windows and single stations can mask long-run variability — flag whenever a multi-year average or one location is used to argue a structural climate shift. |

The reviewer applies **the row matching the `Domain:` value in the call**, plus the general checks in section 7. Other rows are ignored for that run.

## 12. Why this should be a Subagent instead of a Skill

| Aspect       | Skill                                                      | Subagent                                                                  |
|--------------|------------------------------------------------------------|---------------------------------------------------------------------------|
| Job          | Produces the evidence note from the inputs                 | Reviews the evidence note after it has been written                       |
| Context      | Runs in the same chat as the writing work                  | Opens a separate context window — reads cold, no memory of how it was written |
| Bias risk    | Carries the writer's framing into the artifact             | Fresh reader, more likely to catch what the writer no longer sees         |
| How chosen   | Claude selects it automatically when its `description` matches the task | The user explicitly delegates ("use the `research-evidence-reviewer` subagent…") |
| When it runs | Every time the artifact needs to be produced               | Only when a second opinion is wanted before the artifact is shared        |
| Output       | A file (the note itself)                                   | A structured critique printed in chat — not a file                        |
| Analogy      | A recipe followed every time you bake                      | A taster who checks the dish before it is served                          |

If the same activity appeared in both columns, this would be a Skill, not a Subagent. The two columns are genuinely different jobs here — production vs. review — so the Subagent earns its keep. Skills bake the note; this Subagent decides whether the note is safe to serve.

---

### Success check

This Subagent is useful if its review helps the human make a clearer decision **without taking control away from them** — and if the same brief, called with a different `Domain:`, still produces a credible specialist read.
