Research

Usage

/core-skills:research <topic or question> [further user instructions]

Goal

Produce a comprehensive, accurate, deep research document on $ARGUMENTS. Prioritise quality, depth, and accuracy over speed or token efficiency. Save the final document to docs/research/ with today's date prefix.

Protocol

Step 0 — Frame and Pre-Commit

Analyse $ARGUMENTS. Formulate a precise research question — this is the Problem Anchor. Copy it verbatim into every subsequent phase. If the question is too broad to research well, narrow it and tell the user what you scoped to.

Before any research begins, pre-commit resolution criteria: what would a strong answer look like, and what evidence would change the conclusion? This prevents confirmation bias — the test is defined before the results are seen.

Check for prior work: if docs/research/wip/{slug}/ exists, list the files, present what's there, and ask the user:

• Resume — skip completed agents (those with output files), re-dispatch the rest
• Synthesise now — use what's available, skip missing agents
• Restart — delete the wip directory and start fresh

Step 1 — Decompose and Present Plan

Assess complexity. For simple factual lookups, propose 1-2 agents and no review loop. For standard multi-source questions, 3-5 agents and 1 review round. For deep strategic questions, the full protocol. Present this assessment with the plan — the user can override. Never skip the user approval gate, even for Light scope.

If a Light-scope agent returns conflicting evidence or signals hidden complexity, escalate to Standard with user confirmation.

Decompose the research question into orthogonal sub-questions — each with a specific investigative angle and search strategy. Sub-question diversity is the primary quality lever: different questions, different source domains, different search vocabularies (domain-native jargon, not just the user's original phrasing). Include at least one contrarian/adjacent track — an agent exploring non-obvious connections, analogies from other fields, or evidence against the emerging thesis.

Team size proportional to the scope assessment above. Use model: "sonnet" for research agents.

Present the decomposition to the user before spawning agents. Show the scope assessment, sub-questions, agent assignments, and search strategies. Adjust and re-present until the user approves. Skip this checkpoint if the user explicitly requested full autonomy.

Step 2 — Spawn Research Team

Spawn all research agents in parallel using run_in_background: true. Each agent receives:

• The Problem Anchor (verbatim)
• Its specific sub-question and search strategy
• Instruction to cite or flag: cite specific sources for every factual claim — if no source can be found, say so explicitly rather than fabricating
• Instruction to return structured findings: claims with evidence, source citations with URLs, open questions, and what was searched but not found
• Instruction to write output to docs/research/wip/{slug}/{agent-name}.md on completion

Step 3 — Monitor, Recover, Synthesise

Re-read the Problem Anchor and resolution criteria before starting this step.

Wait for all agents to complete. Keep the user updated as agents finish ("3 of 7 done"). If an agent appears stuck (significantly longer than peers), check its output file for progress — if stalled, restart it with a tighter scope. If an agent fails, restart it. Do not proceed with partial results — every sub-question was chosen because it matters.

Once all agents have returned, read all findings. Synthesise — don't just aggregate:

1. Map agreement across agents and assess whether the agreement is independent (different sources) or echo (shared upstream sources citing the same origin)
2. Surface disagreements and explain why agents diverged
3. Identify emergent patterns that no single agent found — cross-domain analogies, implicit assumptions shared by all agents, gaps in the collective coverage
4. Assess claim strength based on evidence quality and source diversity
5. Note genuine uncertainties, gaps, and what was not found
6. Run a pre-mortem: assume the main conclusions are wrong — why might that be? State the key assumptions the conclusions depend on and what would change if each were false

Write the research document. Structure it according to what the content demands — length proportional to complexity and insight density. It must include:

1. The Problem Anchor (verbatim)
2. References (every source cited, with URLs where available)

Save to docs/research/{date}-{slug}.md.

Step 4 — Review Loop

Re-read the Problem Anchor and resolution criteria before starting this step.

Spawn two independent reviewer agents in parallel (model: "sonnet", with different review prompts — one focused on accuracy and gaps, the other on synthesis quality and non-obvious angles). Each receives the research document and the Problem Anchor, and evaluates against:

• Comprehensiveness — major facets covered? significant gaps?
• Accuracy — claims supported by cited sources? unsupported claims?
• Depth — beyond surface-level? mechanisms explained, not just outcomes?
• Source quality — reliable, diverse sources? over-reliance on one?
• Synthesis quality — coherent cross-cutting insights, not just a list?
• Non-obvious insights — anything surprising or unconventional surfaced?

Reviewers must cite specific sections and explain what's wrong or missing. Cooperative framing: "what's missing or unsupported?" — not adversarial.

Step 5 — Address and Converge

Re-read the Problem Anchor and resolution criteria before starting this step.

Read both reviews. Incorporate substantive feedback — with fresh research where gaps were identified (each revision round must introduce external signal; pure self-reflection without new retrieval is prohibited). Push back on feedback that would drift from the Problem Anchor. Update the document on disk.

Record each reviewer finding and its disposition in a markdown table:

Outcome is accepted or rejected with a one-line reason. For rejections, use the existing categories: factually wrong (evidence), would drift from the Problem Anchor (drift), or costs more than it's worth (disproportionate). When a finding is partially accepted, split into two rows. When valid but already addressed, record as accepted: already present, no change needed.

Include this table as a ## Review Process section in the final document. For deep research with multiple review rounds, write the review log to a separate {slug}-review-log.md rather than bloating the main document.

Re-review with two new reviewer agents. Convergence: if both reviewers identify no new substantive gaps or corrections → stop. The test is: "did this round produce actionable feedback that would change the document?"

Hard cap: 3 review rounds (safety net, not a target — most research should converge in 1-2 rounds).

Step 6 — Deliver

Delete docs/research/wip/{slug}/ on successful delivery.

Present the user with:

• Location of the saved research document
• The summary (key findings)
• Any unresolved uncertainties or gaps

Notes

• Do not use role/persona prompting for accuracy — it doesn't work (Mollick et al., 2025). Use task-specific instructions instead.
• Self-refinement without external signal degrades strong model outputs (EVOLVE, 2025; accuracy-correction paradox). Every revision must bring new evidence, not re-reason over the same context.
• If the Write tool fails on a large document, retry with Bash (cat << 'EOF' > file).
• Design rationale: docs/research/2026-03-21-agentic-research-design.md