deep-research

Files (4)

• MAINTENANCE.md
• REFERENCE.md
• SKILL.md
• trigger-cases.json · tests/

SKILL.md (first lines)

# Deep Research

Produce a source-grounded report whose material claims can be audited.
Finish when the scoped questions are supported or explicitly unresolved,
claims pass the shared evidence check, and the finished report is delivered
through the active runtime's output and delivery contract — or, under a
runtime where delivery is coordinator-controlled (the jail), has reached the
written, declared artifacts. Load the runtime's durable user preferences for
this step. Deliver by default unless the user's
current request explicitly opts out; do not ask again whether to send it. The
research coordinator invokes delivery after synthesis and validation. Report
only the state observed, and say the report was emailed only after the
delivery helper verifies receipt.

Single facts and document lookups belong to `research`. Executing workers is a
coordinator function: this thread owns scoping, synthesis, and release, and may
dispatch slices to workers. Fanout is bounded and depth-one — a worker executes
its slice in its own thread and never spawns further workers.

## Scope and decompose

Inspect supplied prior art before searching. Record audience, decision,
recency window, comparison axes, definitions of “best,” exclusions, effort
budget, and a stop rule. Prior reports remain prior-note evidence under the
shared [research evidence contract](../research/EVIDENCE.md); read it before
gathering or checking claims.

Choose the execution shape from the question:

- **Wide:** independent items or slices with comparable outputs. Execute
  sequentially when the set is small or the slices are cheap; dispatch one
  worker per slice when the slices are independent and each is large enough to
  amortize its own context. Dispatch shape is a cost decision, not a correctness
  one — the slice contract is identical either way.
- **Deep:** a dependent source/causal chain, investigated in rounds with a
  replan after each round.
- **Mixed:** enumerate candidates, then investigate a shortlist deeply.

Fan-out is authorized only when all of these hold; otherwise stay sequential:

- slices are independent — no slice consumes another's output;
- each slice carries its own objective, source classes, boundary, acceptance
  condition, and artifact path, so a worker can finish without asking;
- the count is bounded by the budget recorded during scoping, not by how many
  items happen to be enumerable;
- depth is one. A worker returns its artifact; it does not dispatch.

Retain the coordinator's own thread for synthesis. Reading worker artifacts
directly is preferred to a prose relay.

For a large or difficult decomposition, read
[execution shapes](REFERENCE.md#execution-shapes). Give each slice one objective,
source classes, boundary, owner, acceptance condition, and artifact path.
Every requested part belongs to a slice; overlapping searches need an explicit
reason. Keep shared definitions, date window, and comparison axes consistent.

## Gather and synthesize

Open sources that own the claims and record rows using the shared evidence
contract. Each slice must return support or an unresolved item for every
requested part, plus contradictions and its stopping reason. Read artifacts
directly; passing their paths preserves evidence better than a prose relay.

When executing a delegated slice, also read the
[worker contract](REFERENCE.md#worker-contract). Follow its scope and stop rules;
return the slice artifact to the coordinator without publishing it.

Build findings from the captured evidence. Synthesize independent sources
where a claim has multiple owners; for a single-owner fact explain why that
source is sufficient. Preserve conflicting claims and either resolve them with
evidence or name the unresolved disagreement. Replan only around remaining gaps.

## Check and deliver

Apply the shared claim check to the whole report, including uncited prose and
summary claims. Captured, sufficiently current source text can satisfy the
check; refetch when evidence is missing, incomplete, stale, or conflicting.
Stop when the scoped coverage is met, further retrieval repeats evidence,
and remaining uncertainty is explicit. Fix or qualify unsupported wording;
a gap is acceptable only after the relevant search/check work was attempted.

Write one dated report with goal/scope/date, a brief method note, a cited
summary of at most eight bullets, findings organized by the question, a
comparison table when useful, caveats, an answer or recommendation with its
tradeoff, a gap statement, and sources annotated by support/role/retrieval date.
The report must stand alone and its summary must stay within the evidence.

Before delivery, verify scope and slice coverage, evidence links and claim-check
results, conflict dispositions, named gaps, and report date/filename. Use the
runtime's delivery contract by default for the finished report only; plans,
drafts, slice artifacts, and check notes are working material. Honor an explicit
user opt-out. Under a runtime where delivery is coordinator-controlled (the
jail), finish at the written, declared artifacts; never attempt or claim
delivery. Before the coordinator queues a jailed report for PrivateBin/PDF
delivery, a checker worker with a different worker identity must independently verify every
cited claim against its primary source — the source of record, not a secondary
summary — and leave `fact-check.md` beside the report. That file must record
each claim corrected, what changed, and that the correction was rechecked.
Missing `fact-check.md`, missing evidence, or any unresolved failed check blocks
delivery until corrected and rechecked. The coordinator owns this gate. See the
[jailed research delivery rule](../research/REFERENCE.md#jailed-research-delivery).
Report the delivery state actually observed. Say the report was
emailed only after the delivery helper verifies receipt. If the active runtime
offers no delivery mechanism, report that gap and leave the finished report
available.

For evidence rationale and historical cost observations when maintaining this
skill, read [REFERENCE.md](REFERENCE.md#evidence-and-maintenance).

From lstmemery/skills, MIT.

More from lstmemery/skills