Run Deep Research

Run Deep Research

This skill produces a multi-file evidence corpus on disk, never a single chat reply. Per-entity evidence packs, cross-axis comparison rollups, source ledgers, optional profile pages, and a master summary — all written into a navigable folder tree the user can read, edit, link from, and re-enter later. The filesystem is the deliverable.

The orchestrator does not search the web personally. The orchestrator decomposes, architects the folder tree, dispatches research in waves, gates between waves, and synthesizes the final master summary. The actual web research runs on a chosen executor — Claude subagents or codex exec — selected up front at intake (see Executor — Claude subagents or codex). The orchestrator role is identical either way: each research task invokes the run-research discipline (3-tool research surface, ## Not found harvesting, citation rules, parallel scope dispatch). The filesystem is the only context channel between waves — research tasks do not see each other's outputs except through files the orchestrator names in the next brief.

When to use this skill

Trigger on any of these phrasings:

• "research / compare / evaluate 5+ tools / vendors / projects / frameworks"
• "market analysis of [category] / competitive landscape / category map / competitor research"
• "build a research corpus / evidence pack / decision corpus on [category]"
• "deep research on [SaaS / OSS / dev-infra / data-API / regulated category]" with per-vendor pages
• "give me pricing + capability + integration + security + audience matrices across [vendors]"
• "navigable folder of product pages, comparison rollups, source ledgers, and profile pages"
• "every numeric / versioned / priced claim must cite a verbatim source quote"
• "the deliverable is a folder tree the team can navigate", not a chat reply
• "audit / shortlist [population]" against a fixed axis catalog (cost, performance, fit, risk, longevity)
• The user names 5+ vendors / projects upfront and asks for a structured side-by-side
• "use codex for the research", "run this through codex exec" — same corpus, codex executor (an intake choice, not a different skill)

Do NOT use when:

The fence: run-research answers one question and returns one synthesis; this skill answers N questions across N entities and returns a multi-file corpus. If the deliverable is a folder, you are in this skill. If it's a chat reply or a single Markdown file, you are in run-research.

Intake — always ask first (AskUserQuestion)

Before any decomposition, template authoring, or dispatch, run one batched AskUserQuestion call to lock the run's shape. This is mandatory — never start a heavy pass on assumptions, and never burn fan-out budget before the user has confirmed the executor. Batch the discrete decisions into a single call so the user answers once; make the recommended default the first option of each:

1. Executor — Claude subagents (default) · codex exec (cheaper/faster large fan-out) · decide by fan-out size.
2. Scale — compact (5-10) · standard (10-40) · deep (40-100) · tiered (100+).
3. Framing — domain-agnostic corpus · industry / vendor category.
4. Scope — discover entities vs. use the user's named list; confirm the <topic-slug>/ output folder and whether profile pages are wanted.

Capture the decider and use case from the conversation (or the question's free-text notes) — these anchor _meta/01-charter.md; without them "good" and "bad" are undefined. If AskUserQuestion is unavailable (non-interactive run), fall back to the stated defaults and record the assumption in the charter. Full question wording, option sets, recommended defaults, and the headless fallback: references/intake.md.

The intake answers seed Phase 0: executor + scale + framing go straight into the charter; the codex executor additionally requires a per-wave effort plan (§Executor).

The orchestrator's mental model

Every deep-research question reduces to one shape: a population of entities, evaluated across a set of axes, producing per-entity evidence packs + per-axis cross-entity comparisons + a master decision artifact. Strip away the domain and that shape remains.

The four invariants in every session:

• A finite set of entities. The unit researched one folder per (products, candidates, projects, providers, papers, plans). The orchestrator's first job is to enumerate and tier them.
• A finite set of evaluation axes. Dimensions the decider weighs (cost, performance, fit, risk, longevity, compliance). Each has a native primitive (currency-per-period, milliseconds, score). Without native primitives, comparison is incoherent.
• A decider with a use case. Without this, "good" and "bad" are undefined.
• A decision artifact. Without this, the research has no closing condition.

The orchestrator's four jobs in order:

1. Decompose — what are the entities, what are the axes? See references/thinking.md. Without rigorous decomposition, no amount of evidence saves the corpus.
2. Structure — design the folder tree, file-naming scheme, MAX-N ceilings before any research dispatches. See references/filesystem.md.
3. Dispatch — write briefs that bind each research task to its specific scope, the run-research discipline, and the exact file paths it owns. See references/subagent-briefs.md (Claude) or references/codex/codex-prompt-skeleton.md (codex).
4. Synthesize — read every output file personally; resolve contradictions; write the master summary. See references/synthesis.md.

Filesystem as context channel

This is the load-bearing principle of every wave-based orchestrated session.

• Each research task receives only the files the orchestrator names in its brief.
• Each research task writes only to the folder the orchestrator assigned.
• The orchestrator reads outputs after each wave and decides what the next wave reads.
• No research task sees another's working notes, search history, or mid-stream outputs — only the persisted files the orchestrator chooses to share.

This is what makes the wave model scale. With more than two or three research tasks in flight, in-memory context collapses. With files, the wave model composes cleanly to dozens of entities and multiple sub-waves. Treat <corpus-root>/ as the shared blackboard; treat each research task's prompt as a narrow read-write contract against that blackboard. (The contract is identical whether the task is a Claude subagent or a codex exec job — only the executor differs.)

Operational consequences:

• Briefs name input paths (what the task reads) and output paths (what the task writes), explicitly and exhaustively.
• Write scopes between sibling tasks in the same wave are disjoint — no two tasks own the same folder.
• Between waves, the orchestrator reads every file produced. This is not delegable.
• If a task needs evidence from another task's output, that evidence is passed through a file the orchestrator surfaces in the next wave's brief — never through "ask the other agent."

Two framings, same skeleton

The methodology is domain-agnostic. The output structure has two named defaults — pick once at Phase 0 and stay consistent. Both produce the same kind of multi-file evidence corpus; the difference is vocabulary and which reference files are loaded.

Framing is resolved at intake. If the user's framing is genuinely ambiguous (e.g., "research 8 LLM providers" — both fit), the intake's framing question settles it; do not switch mid-session. Switching framings mid-run forces a corpus rewrite.

Executor — Claude subagents or codex

Research-doing waves run on one of two executors, chosen once at intake and recorded in the charter. Corpus shape, wave model, templates, and the filesystem-as-context discipline are identical — only who performs each web search differs.

What never changes between executors: the orchestrator owns decomposition, folder tree, file naming, template authoring, between-wave reads, and the master summary. Phases 0/2/3/7 and the synthesis waves (Wave 3, profile-page Wave 4) are orchestrator-personal regardless of executor.

When codex is chosen, its load-bearing mechanics — exec flag spine, idempotent skip-existing, one answer file per job, bounded concurrency (8/wave, 32 ceiling), rendered prompt files on disk, per-wave effort routing, and the preflight auth gate — live in references/codex/:

Pinned defaults

Phase model

Eight phases, each with an artifact gate. Skip a phase only when its artifact is not needed for the user's stated outcome — and state the reason.

Research-doing waves (1, 2, optional 4-promoted) run on the chosen executor — Claude subagents invoking run-research, or codex exec jobs. Wave 3 and profile-page Wave 4 are LOCAL-ONLY synthesis — read files, no web tools. Phases 0, 2, 3, 7 are orchestrator-personal — no delegation, regardless of executor.

Full wave choreography, brief structure, between-wave gates: references/orchestration.md (Claude) and references/codex/wave-dispatch.md (codex).

Tool steering at a glance

The orchestrator chooses the tool category for each use case in the brief; the research task executes it (a Claude run-research session, or a codex exec job).

Every research-doing wave inherits two rules from the tool contract: only extract-evidence findings with verified quotations are citable, and a result carrying continuation.required: true must be finished by invoking its exact continuation.next_call in the same session before that task reports back.

For tool API, fallback chains, and operational thresholds (URL counts, requirement counts, parallel calls), the brief points to the run-research tool reference. For industry-framing graceful degradation (Powerpack → WebSearch → curl chain), see references/industry/research-powerpack-and-explore.md.

Output architecture contract

Domain-agnostic framing default tree:

<corpus-root>/
├── README.md                                       (entry point)
├── _meta/                                           (MAX 8 files)
│   ├── 00-master-summary.md                        (Phase 7)
│   ├── 01-charter.md                               (Phase 0; Wave 1 resolves)
│   ├── 02-entities.md                              (Wave 1A output)
│   ├── 03-axes.md                                  (Wave 1B output)
│   ├── 04-product-template.md                      (Phase 2)
│   ├── 05-axis-templates.md                        (Phase 2)
│   ├── 06-file-budget.md                           (Phase 3)
│   └── 07-dispatch-log.md                           (running log)
├── <entity-slug>/                                   (one per core; MAX 15 files)
│   ├── 00-overview.md
│   ├── 01-<axis-1>.md ... 0N-<axis-N>.md
│   └── 09-sources.md
├── <entity-slug>.md                                 (optional profile at root)
└── _cross/
    └── <axis-slug>/                                (MAX 12 files)
        ├── 00-overall-comparison.md
        └── 01-<scenario>.md ...

Industry framing default tree:

<topic-slug>/
├── README.md
├── _meta/
│   ├── research-plan.md
│   ├── _PRODUCT_TEMPLATE.md                        (Phase 2 maximalist template)
│   ├── _COMPARISON_TEMPLATE_<criterion>.md         (Phase 2 per-criterion)
│   ├── methodology-and-source-policy.md
│   ├── discovered-entities.md
│   └── file-budget.md
├── _cross-<scope>/
│   ├── 00-overview/
│   ├── <criterion-a>/
│   ├── <criterion-b>/
│   └── 09-sources/
├── <entity-slug>/
│   ├── 00-overview/
│   ├── <vertical-context-1>/
│   ├── <vertical-context-2>/
│   └── 09-sources/
└── <entity-slug>.md                                 (profile page; Phase 6)

When the executor is codex, a per-run workdir sidecar (prompts/, logs/, status/, audit/, run.json) tracks the fanout state alongside the corpus — codex writes answers directly to the final corpus paths via -o. See references/codex/wave-dispatch.md for the sidecar layout.

Concrete folder + file naming rules, MAX-N ceilings, numbered-prefix scheme, and the agent-chosen-filename rule: references/filesystem.md. Vertical-specific category names (SaaS, OSS, dev-infra, data/API, regulated, consumer): references/industry/category-taxonomies.md.

Numeric prefixes are scan order, not semantic naming. Filenames within each numbered subfolder are agent-chosen based on the evidence found for that specific entity. Two research tasks may legitimately land different filenames in the same numbered subfolder — that is correct.

Hard rules (load-bearing)

These break the corpus when ignored. Keep them at the top of mind.

1. Run the intake AskUserQuestion batch before any wave. Executor, scale, and framing are locked at intake and recorded in the charter — never start a heavy pass on assumptions.
2. The orchestrator does not search. Searching is the research task's job, via the run-research discipline embedded in its brief (Claude subagent or codex job).
3. The orchestrator does not delegate synthesis. Read every entity pack and every cross file personally before the master summary.
4. Templates first, files second. Phase 2 (template authoring) MUST complete before any entity-pack or cross-comparison file is written. Skipping templates is a hard failure — depth varies per task and comparability is lost.
5. Maximalist templates, not generic skeletons. A thin _PRODUCT_TEMPLATE.md (≤15 sections) means Phase 1's deep category pre-pass was skipped. Re-do it. Target ~30+ vertical-specific sections.
6. MAX 8 tasks per wave (domain-agnostic) / MAX 20 per wave (industry). Beyond the cap, run sequential sub-waves. For the codex executor, concurrency is bounded at 8/wave, 32 ceiling. Coordination overhead exceeds parallelism savings above the cap.
7. Disjoint write scopes. Each research task owns exactly one folder. No two tasks in the same wave write to the same path.
8. Every research-doing brief invokes run-research. Embed the run-research integration block verbatim — see references/subagent-briefs.md (Claude) or references/codex/codex-prompt-skeleton.md (codex).
9. Every numeric / versioned / priced claim cites a verbatim quote. Snippet citations are forbidden.
10. No placeholder / stub files. A template section with no evidence becomes a one-paragraph "insufficient evidence" entry inside an existing file in the same subfolder, naming the specific data gap. Never a stub file.
11. Folder names are vertical-specific, filenames are agent-chosen. The orchestrator chooses subfolder names per category (Phase 2). Research tasks pick the 01-meaningful-title.md filenames inside those folders based on the evidence they surface.
12. Separate confirmed facts, vendor/project claims, practitioner evidence, and inference. Never treat snippets as evidence. Never present Reddit as "consensus" without per-comment attribution.
13. Two-level orchestration only. Research tasks do not create their own sub-tasks (no subagent spawns a subagent; no codex job spawns a codex job).
14. No single-report output. This skill produces a multi-file corpus. If the user wants a single report, redirect to run-research.
15. MAX-N caps are ceilings, not targets. 15 per entity / 12 per cross-axis / 8 per meta. Below ceiling is normal; sparse evidence is acceptable. See references/filesystem.md.
16. Codex executor: idempotency is load-bearing. Skip-existing is the default retry strategy; one answer file per job; every job gets a rendered prompt file on disk; an empty answer is failed, not done; between-wave reads are still non-delegable. Full contract: references/codex/wave-dispatch.md and references/codex/codex-exec-contract.md.

If any rule is violated, the rest of this skill stops applying — stop, recover, and resume only after the violation is corrected.

Self-correction triggers

If you notice yourself doing any of the following — stop:

• Dispatching any wave before the intake AskUserQuestion batch is answered → STOP. Run intake first; lock executor, scale, framing.
• Skipping Phase 2 templates and dispatching Wave 2 directly → STOP. Templates are the comprehensiveness contract.
• Writing a thin or generic product template (≤15 sections) → STOP. Re-do Phase 1's deep category pre-pass; re-author with ~30+ distinct sections. See references/industry/template-authoring.md.
• Hardcoding filenames in the template → STOP. Templates list sections + questions; tasks pick filenames per their evidence.
• Letting a research task silently skip a template section → STOP. Every section gets content OR an explicit one-paragraph "insufficient evidence" entry naming the gap.
• Dispatching more than the cap (8 domain-agnostic / 20 industry; codex 8/wave) in one wave → STOP. Coordination overhead exceeds parallelism savings. Split into sub-waves. See references/orchestration.md.
• Summarizing Reddit as "consensus" without per-comment attribution → STOP. Apply the audience-evidence fields from references/synthesis.md / references/industry/evidence-and-synthesis.md.
• Treating a vendor's marketing page as confirmed fact → STOP. Re-classify per source hierarchy; vendor claims belong in the vendor-claim ledger row.
• Searching the web yourself as the orchestrator → STOP. Dispatch a research task. Searching is the task's job, via run-research.
• Delegating synthesis → STOP. Read every core pack and every cross folder personally before writing the master summary.
• Producing a single-report output ("here's the markdown report") → STOP. This skill produces a multi-file corpus. If the user wants a single report, redirect to run-research.
• Codex: choosing medium for every wave by accident, or marking an empty answer done → STOP. Pick per-wave effort up front; empty = failed. See references/codex/effort-routing.md and references/codex/wave-dispatch.md.
• Skipping the completion gate ("looks done") → STOP. Run the verification commands in references/verification.md. Template-coverage audit, link check, source-ledger presence are non-negotiable.
• Research task stalled, timed out, or returned shallow output → STOP improvising. Apply the recovery procedures in references/failure-modes.md (Claude) or references/codex/orchestrator-cookbook.md (codex).

Anti-patterns

Output contract

Show these artifacts at the phase that produces them. Never batch all artifacts to the end.

1. Phase 0 — scope statement + corpus scale + framing (domain-agnostic / industry) + executor (Claude / codex) + (if codex) the per-wave effort plan.
2. Wave 1 — discovered entities table (tier + source URL + 1-line rationale) AND axis catalog AND category-understanding note (industry framing).
3. Phase 2 — resolved category list AND the maximalist product template AND each cross-axis / cross-criterion template. Show inline (or summarized with link) — they are the comprehensiveness contract for the rest of the work.
4. Phase 3 — file-count expectation derived from templates + tree shape + the Wave 2 dispatch map (which task owns which entity; for codex, slug → entity → effort).
5. Wave 2 — dispatch map, then evidence-pack progress notes as tasks complete (codex: dispatch envelope + audit summary at wave end).
6. Wave 3 — cross-axis / cross-criterion ranking summary.
7. Wave 4 (optional) — profile-page index.
8. Phase 7 — completion statement (path, files, entry points, gaps, verification, template coverage; for codex, total jobs and terminal states).

Reference routing

Load only the reference whose phase is active. Loading all references at once exhausts context.

Quick start

The first five minutes of any session:

1. Intake — run the single batched AskUserQuestion call (executor / scale / framing / scope). See references/intake.md. Never dispatch a wave before this is answered.
2. Phase 0 — write _meta/01-charter.md from the intake answers + decider/use-case. Read references/thinking.md and references/templates.md (or references/industry/discovery.md + references/industry/template-authoring.md for industry framing) for the charter format. State framing + executor explicitly; if codex, write the effort plan (references/codex/effort-routing.md).
3. Wave 1 — dispatch parallel discovery + scope tasks in one tool message. Both invoke run-research. Use references/subagent-briefs.md (Claude) / references/industry/mission-briefs.md (industry), or references/codex/codex-prompt-skeleton.md + references/codex/wave-dispatch.md (codex). Wait for both. Read every output personally.
4. Phase 2/3 — read Wave 1 outputs; write templates per references/templates.md or references/industry/template-authoring.md (industry, keystone); plan architecture per references/filesystem.md or references/industry/industry-architecture.md. Optionally scaffold with scripts/init-corpus.sh <topic-slug> (see scripts/init-corpus.md). Show the architecture to the user before Wave 2.

After that, the loop is: Wave 2 (per-entity, possibly multiple sub-waves) → Wave 3 (per-axis cross) → optional Wave 4 → Phase 7 verification + master summary. Wave choreography lives in references/orchestration.md (Claude) and references/codex/wave-dispatch.md (codex); the Phase 7 gate procedure lives in references/verification.md and references/synthesis.md.

If anything is unclear, the question is almost always upstream: read references/thinking.md and clarify the decomposition before dispatching more tasks.

Guardrails

• Do not make landing-page-style reports. Build the actual research corpus.
• Do not collapse product facts, pricing, practitioner sentiment, and source verification into one undifferentiated file.
• Do not create raw dump folders unless the user explicitly asks. Summarize and source-map instead.
• Do not use the same category names for every vertical when better names are available.
• Do not outsource final synthesis. The orchestrator reads the files and resolves contradictions personally.
• Do not exceed the per-wave cap. Run multiple waves instead.
• Do not let research tasks create sub-tasks. Two-level orchestration only.
• Do not start Wave 2 entity research before Phase 2 templates are written and shown to the user.
• Do not declare completion without running the Phase 7 verification, including the template-coverage audit.

Bottom line

Ask the intake batch → decompose into entities × axes → architect the folder tree → dispatch research in waves (Claude subagents or codex exec) through filesystem-bound briefs → between waves, read everything personally → write the master summary → run the verification gate. The filesystem is the deliverable, the context channel, and the audit trail in one. If the deliverable is anything other than a folder of source-backed evidence files, this is the wrong skill.