deep-research

# Deep Research V8.0

This skill is for **evidence-rich research outputs**, not for every question that happens to mention “analysis”.

The V8 shift is simple:
- **Single-agent first.** Start with one lead agent and only fan out when parallel work will clearly help.
- **Thin harness, fat skill.** Put reusable judgment and workflow here; keep deterministic checks in scripts.
- **Context organization over prompt stuffing.** Load the minimum active context bundle, then pull in references only when needed.
- **Eval and observability built in.** A good report is not enough; the run must also be diagnosable and improvable.

## What this skill should produce

Choose the lightest artifact that satisfies the task.

| Output type | Use when | Typical length | Required artifacts |
|---|---|---:|---|
| **Brief memo** | user wants a concise answer with evidence | 800-1800 words | `research-plan.md`, `registry.md`, `draft.md`, `run-summary.json` |
| **Full report** | user asks for comprehensive analysis / literature review / decision document | 2500-6000 words | all core artifacts + `evaluation.md` |
| **Delta update** | user says “continue”, “second round”, “what changed”, “deepen round 2” | 600-1800 words | prior round handoff + new notes + delta draft |

If the user did **not** ask for a long report, default to **Brief memo**.

## When NOT to use this skill

Do **not** activate for:
- quick fact lookups or simple definitions
- summarizing a single provided article/PDF/page
- short comparisons the model can answer directly from 1-2 sources
- brainstorming without evidence requirements
- tasks where the user explicitly wants a short answer, not a report

If in doubt, ask yourself: **Does this task need a reusable evidence artifact and multi-source synthesis?** If not, do something simpler.

## Org-policy boundary

This skill does **not** replace system policies, enterprise guardrails, or repo-level instructions.
Put these outside the skill:
- data handling / PII / compliance rules
- approval requirements for external access or irreversible actions
- org-wide style and review policy
- environment-specific permissions

Keep those in system prompts, AGENTS/CLAUDE/OpenAI config, or the harness. This skill owns the **workflow**, not the company’s permanent red lines.

## Active context bundle

At activation time, keep the active bundle small.

**Always load first**
1. This `SKILL.md`
2. `references/methodology.md`
3. `references/report-assembly.md`
4. `references/research-notes-format.md`

**Load on demand**
- `references/subagent-prompt.md` only if you actually dispatch subagents
- `references/evaluator-prompt.md` only if you run the evaluator
- `references/quality-gates.md` before finalization
- `references/observability.md` when emitting metrics or diagnosing regressions
- `references/tension-discovery.md` only for contested / decision-heavy topics
- `references/landscape-scan.md` only when literature or ecosystem mapping matters

**After compaction or context reset**
Reload only:
- `research-plan.md`
- active task notes
- `registry.md`
- unresolved issues list
- the one reference file for the current phase

Do **not** reload the whole skill tree unless the run drifted badly.

## Workflow

### P0 — Scope, route, and choose the lightest mode

Create `workspace/research-plan.md` with:
- research question
- intended audience
- freshness requirement
- geography / market / jurisdiction
- output type (brief / full / delta)
- stakes: low / medium / high
- why this skill is justified

Then choose the orchestration mode:

| Mode | Default choice |
|---|---|
| **Single-agent** | default for most tasks |
| **Lead + subagents** | only when there are 3+ separable research threads or obvious parallel value |
| **Delta update** | when continuing prior research |

**Do not fan out just because subagents exist.**

### P0.5 — Optional modules (not mandatory by default)

Use optional modules only when they earn their keep:
- **Tension discovery** (`references/tension-discovery.md`): use for contested, hype-heavy, or decision topics where mainstream framing may be wrong.
- **Landscape scan** (`references/landscape-scan.md`): use when the domain is unfamiliar, broad, or literature-heavy. For non-academic topics, this can be an ecosystem/standards/vendor scan rather than arXiv.
- **Reverse search**: use when costs, failure modes, counter-evidence, or operational constraints are missing.

### P1 — Plan the evidence work

Break the task into 1-5 research threads. Each thread needs:
- one crisp objective
- starting queries
- what “done” looks like
- what evidence would change the conclusion

If using subagents, each subagent gets **one** focused thread. Avoid overlapping ownership.

### P2 — Investigate, extract, and write notes

Follow `references/research-notes-format.md`.

Rules:
- search broadly first, then chase named entities, standards, datasets, products, trials, laws, or papers
- fetch and read the best supporting sources for the highest-value claims
- write notes that separate **facts**, **analysis**, **gaps**, and **unresolved conflicts**
- capture support snippets/paraphrases for the top claims so later verification is easier

The lead agent should work from notes **by default**, but may inspect raw/fetched sources again when:
- two sources materially conflict
- a claim is high-stakes or decision-critical
- a note looks suspiciously weak or over-compressed

### P3 — Build registry and verify evidence

Create `workspace/registry.md` from approved sources only.

Use `scripts/source_evaluator.py` as a **helper**, not an oracle.
Authority scores are heuristics. Final acceptance depends on claim fit, evidence type, and whether the source can actually bear the weight of the claim.

Use `scripts/verify_citations.py` before finalization.

Evidence rules:
- core claims should lean on the strongest available evidence for that claim type
- anecdotes illustrate; they do not anchor the conclusion
- conflicting evidence must be