Research Playbooks

---
description: Orchestrate evidence-based playbook scoping research for the neuro-coscientist project. Three phases: scope survey, core-set outlines, synthesis.
---

# /research-playbooks

You orchestrate evidence-based playbook scoping research for the
neuro-coscientist project. State lives at `research/playbooks/STATE.md`.
Begin every invocation by reading STATE.md to know what phase the project
is in and what has been completed. Read `VISION.md` if context is unclear.

## Subagent invocation

Invoke both subagents the canonical way `run-m1` does: `Use the Agent tool with
subagent_type: "playbook-researcher"` and `Use the Agent tool with subagent_type:
"playbook-critic"`. Every "Invoke …" / "Spawn …" instruction below means exactly that.

## STATE.md schema

Markdown file with sections per phase, each recording:

- `status` — `not_started` / `in_progress` / `complete`
- `started_at`, `completed_at`
- `producer_output` — path to the `playbook-researcher` output (e.g.
  `phase1_scope_survey.md`)
- `critique_output` — path to the matching `playbook-critic` output
  (e.g. `phase1_critique.json`). For Phase 2, list per-batch critique
  paths.
- `critique_verdict` — `accept` / `revise` / `reject` (per-batch for
  Phase 2)
- `revisions_used` — 0 or 1 (the workflow allows at most one revision
  cycle per item)
- `final_status` — `accepted_clean` / `accepted_with_concerns` /
  `rejected_and_redone`
- `notes`

There is a "current phase" pointer at the top.

## Fact-checking discipline (the playbook-critic)

Every producer output is fact-checked by `playbook-critic` before it is
treated as final. The critic is read-only on the outline files and uses
WebSearch / WebFetch to verify citations, attributions, technical
details, pitfall plausibility, dependencies, and cross-playbook
consistency. The critic writes a `critique.json` to a path specified in
its invocation prompt and returns a verdict of `accept` / `revise` /
`reject`.

Critic invocation rules:

- **accept**: proceed; log the critique path in STATE.md.
- **revise**: re-invoke `playbook-researcher` with the full critique
  pasted into its prompt and an explicit instruction to address every
  high-severity and medium-severity concern by either correcting the
  claim with a verifiable citation (verified by re-search before the
  revision is written) or removing the claim. Then re-invoke the critic
  on the revised output. **Iterate this loop until the critic returns
  `accept`.** There is no fixed cap — the workflow does not move
  forward until the critique accepts. Log every cycle in STATE.md
  `notes` (cycle index, verdict, concern counts) so the trajectory is
  visible. As a safety, if `revisions_used` reaches 5 without
  convergence, pause and surface the trajectory to the user — that
  usually means the producer prompt itself needs tightening, which is
  the user's call.
- **reject**: the output cannot be rescued by revision. Surface the
  high-severity concerns to the user and stop. The user decides whether
  to redo from scratch with explicit fact-grounding instructions.

When concatenating per-batch outputs into a phase output file (Phase 2),
append per-batch critique summaries as a final `## Fact-check trail`
section so the provenance is preserved.

## Phase 1 — Evidence-based scope survey

Producer output: `research/playbooks/phase1_scope_survey.md`.
Critique output: `research/playbooks/phase1_critique.json`.

1. Invoke `playbook-researcher` with the appendix prompt
   ("Phase 1 subagent prompt") to produce the survey.

2. **Fact-check via `playbook-critic`.** Invoke `playbook-critic` with a
   prompt instructing it to fact-check the full survey at
   `phase1_scope_survey.md` and write its critique to
   `phase1_critique.json`. Read the critique.

   - If `verdict: "reject"`: surface the high-severity concerns to the
     user and stop. The user decides whether to redo Phase 1 from
     scratch.
   - If `verdict: "revise"`: re-invoke `playbook-researcher` with the
     critique pasted in and instructions to address every high-severity
     and medium-severity concern (correct with a verifiable citation
     re-checked via search before writing, or remove the claim). Then
     re-invoke `playbook-critic` on the revised survey, overwriting
     `phase1_critique.json`. **Iterate this loop until the verdict is
     `accept`.** No fixed cap; pause and surface to the user only if
     `revisions_used` reaches 5 without convergence.
   - If `verdict: "accept"`: log the critique path and proceed.

3. Phase 1 gate: show the user a one-screen summary of the survey's
   findings (top categories that emerged, count of classes in core vs
   extended set, anything unexpected) **and** a summary of the critique
   (verdict, count of high-severity concerns, headline issues). Wait
   for the user's `proceed` before marking Phase 1 complete in STATE.md.
   If the user requests revisions on scope rather than facts, re-invoke
   the producer with the user's feedback added to its prompt, then
   re-run the critic.

## Phase 2 — Outlines for the core set

Producer output: `research/playbooks/phase2_playbook_outlines.md`.
Per-batch producer outputs: `research/playbooks/_phase2_batch_<N>.md`.
Per-batch critique outputs: `research/playbooks/_phase2_batch_<N>_critique.json`.

1. Read the Phase 1 survey. Identify the playbooks in the recommended
   core set. Group them into batches of 5-7 playbooks per subagent
   invocation, batched by the emergent categories from Phase 1 so each
   subagent gets coherent groupings.

2. Spawn `playbook-researcher` subagents in parallel — **never more
   than 6 concurrently** to respect Max rate limits. Each subagent
   receives: the survey file, the 7-field outline schema (below), and
   its specific batch. Each writes to
   `research/playbooks/_phase2_batch_<N>.md`.

3. **Fact-check each batch via `playbook-critic`.** After a batch
   returns, invoke `playbook-critic` with a prompt instructing it to
   fact-check `_phase2_