# Section 8 — Subagents

## What this section does

1. **Design** one specialist Subagent (`research-evidence-reviewer`) that can be parameterized for any research domain (healthcare, education, policy, climate, etc.).
2. **Run** the ready-made copy of that subagent that ships pre-installed inside this section, so you can feel how `@<agent-name>` actually behaves.
3. **Compare** the brief you designed against the file Claude actually loads at `.claude/agents/research-evidence-reviewer.md` — and check the brief is not just the Skill in another shape.

## What you'll do (and what you'll see)

You don't write code. You paste prompts into Claude and end up with **two files in `outputs/`** plus **two specialist critiques printed in chat**. The two parts below are independent — do them in either order.

### Part A — Design (1 paste → 1 file)

| You paste | You get |
|---|---|
| The Track A prompt below | `outputs/subagent-brief.md` — your design doc with domain parameters and a Skill-vs-Subagent comparison table |

### Part B — Run (4 pastes → 1 new file + 2 chat critiques)

| Step | You paste | You see |
|---|---|---|
| 1 | `ls .claude/agents` (in your terminal, not Claude) | Proof the subagent file is installed |
| 2 | "Read the subagent file and explain its description / tools / output" | Claude explains the file back — no invocation yet |
| 3 | "Write a deliberately rough draft at `outputs/evidence-note.md`" | A new file: `outputs/evidence-note.md` with caveats missing on purpose |
| 4 | `Use the research-evidence-reviewer subagent on outputs/evidence-note.md. Domain: healthcare.` | A 5-section critique from a **separate context** — and the subagent refuses to edit the note |
| 5 | Same prompt, `Domain: policy.` | Same draft, **different specialist read** — the Risks section shifts shape |

The critiques in Steps 4 and 5 print in chat; they are **not** saved as files. That's deliberate — you should *feel* the subagent run as its own session.

### Compare (self-check at the end)

Open `outputs/subagent-brief.md` (your design) next to `.claude/agents/research-evidence-reviewer.md` (the working one). They won't match perfectly — that's fine. Ask yourself: would your brief still earn the name **subagent**, or did it drift into Skill territory?

### What you should feel by the end

- A subagent runs in a **separate context** — fresh eyes, not shared chat memory.
- The same brief **specializes at call time** (`Domain: healthcare` vs `Domain: policy`).
- A subagent **enforces its boundary** — it won't edit the file it just reviewed.
- **Subagent vs Skill:** Skills *produce* recurring artifacts; subagents *judge* artifacts from a fresh context.

## Launch Claude Code from this section folder

```bash
cd 08-subagents
claude
```

Subagents only auto-discover from `<cwd>/.claude/agents/`, so you must launch from inside `08-subagents/` for the subagent to be found.

```text
08-subagents/                         ← launch claude from here
  .claude/
    agents/
      research-evidence-reviewer.md   ← pre-installed; Claude Code auto-discovers it (also your side-by-side reference)
  subagent-brief.template.md          ← structure cue for your Track A brief
  outputs/
    subagent-brief.md                 ← your Track A design artifact
    evidence-note.md                  ← (Track B) the draft the subagent reviewed
  inputs/
    BRIEF.md                          ← evidence rules and suggested output shape
    data-table.csv                    ← World Bank physician-density extract
    reference-document.pdf
    screenshot-or-chart.png
    raw-message.txt
```

The two tracks below are independent. Track A is the required artifact; Track B is the hands-on with the installed subagent. Do A first if you've never written a subagent brief; do B first if you'd rather feel the tool before designing your own.

---

## Track A — Prompt: Create the parameterized Subagent brief

> Paste into Claude Code from inside `08-subagents/`.

```text
Look at one or two source files in ./inputs/.
Also read CLAUDE.md if it exists.
Use subagent-brief.template.md as the structure cue.

Design ONE specialist Subagent named `research-evidence-reviewer`
that I can parameterize by domain, and write the full brief to
outputs/subagent-brief.md with these sections:

1. why this name is generic enough to parameterize by domain
2. what this subagent is
3. why I would delegate this work
4. when to use it
5. when to use another Claude Code tool instead
6. inputs it should inspect
7. process it should follow
8. ideal output format
9. boundaries: what it should never edit or decide alone
10. how I would call it during real work
11. a short "Domain parameters" section showing how the same brief specializes
   for at least three domains: healthcare, education, and one other
   (for example: policy, climate, or workforce). For each domain, write
   one line of domain-specific evidence-handling rules.
12. why this should be a Subagent instead of a Skill (use the
    Skill-vs-Subagent table from the template)

Keep the brief plain-language and beginner-friendly.
Write the file in one pass — do not stop to ask for confirmation.
```

---

## Track B — Run the pre-installed subagent

The subagent is already installed at `.claude/agents/research-evidence-reviewer.md` inside this section folder. Claude Code auto-discovers it the moment you launch from `08-subagents/`. Open that same file in your editor when you want a side-by-side read against your Track A brief.

> **Project agent, not global.** It is installed into `08-subagents/.claude/agents/` so the subagent is scoped to this section only. The global location is `~/.claude/agents/` (available across every project on your machine) — we are intentionally **not** using that.

### Step 1 — Confirm it is there (terminal, **not** inside Claude Code)

```bash
ls .claude/agents
# expect: research-evidence-reviewer.md
```

> Windows PowerShell: `dir .claude\agents`

### Step 2 — Read it back

Paste into Claude Code:

```text
A subagent is pre-installed at .claude/agents/research-evidence-reviewer.md.

Read it, then tell me:
1. What is the exact `description` line? Is it specific enough that I would
   reach for this subagent instead of a one-off prompt?
2. Which `tools` does it limit itself to, and why those?
3. What does its output format look like, and what does it refuse to do?

Do not invoke the subagent yet. Just read it and explain it back to me.
```

### Step 3 — Create a tiny draft note to review

The subagent reviews a *draft*. If you don't already have one in `outputs/`, ask Claude to write one:

```text
Write a short draft evidence note at outputs/evidence-note.md
using only the files in inputs/.
Keep it to 6 sections following the "Suggested Output Shape" in inputs/BRIEF.md.
Do NOT polish it — leave the obvious caveats missing on purpose so the
reviewer subagent has something to flag.
```

### Step 4 — Invoke the subagent on the draft

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

You should see the subagent open a separate working context, read the draft + inputs, and return the 5-section output defined in its file (Summary judgment / What works / Risks or gaps / Suggested changes / Questions for the human owner). It should refuse to edit the note.

### Step 5 — Swap the domain parameter

Run the same call again with a different domain to feel the parameterization:

```text
Use the research-evidence-reviewer subagent on outputs/evidence-note.md.
Domain: policy.
```

The Risks/Gaps section should change shape — same brief, different specialist read.

---

## Optional advanced branch

- Edit `.claude/agents/research-evidence-reviewer.md` — tighten the `description` line so it triggers without needing the name. Compare what changes.
- Run `/agents` inside Claude Code to see the installed subagent in the management UI.
- Add a new domain row to the subagent's "Domain rules" table for a domain you actually work in.

## If it goes wrong

| Problem | Fix |
| --- | --- |
| Claude doesn't pick up the subagent | Mention `@research-evidence-reviewer` by name in your prompt to force invocation. |
| Subagent rewrites the note instead of reviewing | Its boundary said not to. Reload the file and re-run; if it still rewrites, your prompt was too open — say "review only, do not edit". |
| "File does not exist" | Run Track B Step 3 first to create `outputs/evidence-note.md`. |
| Claude says it can't find the subagent | Confirm you launched `claude` from inside `08-subagents/`. Subagents auto-discover from `<cwd>/.claude/agents/` only. |
| Want it gone | `rm .claude/agents/research-evidence-reviewer.md` removes it from this section only. |
