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:

| Situation | Use instead | |---|---| | One technical question, single answer | run-research | | 1-4 entities, one polished single-page summary, no folder structure | run-research | | Finding or shortlisting GitHub repos as the deliverable | run-github-scout | | Many small factual web questions, one parseable answer file each | search-it-bulk-by-codex | | Codebase analysis, code review, or implementation work | not this skill | | Polished single deliverable (HTML battlecard, slide deck) | downstream skills polish |

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 / 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 / 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 | Trigger | Default output flavor | Load first | |---|---|---|---| | Domain-agnostic corpus | "compare / research / evaluate N entities" in any domain (OSS projects, models, hardware, papers, candidates, locations, regulations, frameworks) | _cross// rollups; _meta/04-product-template.md + _meta/05-axis-templates.md | references/thinking.md, references/filesystem.md, references/orchestration.md, references/templates.md | | Industry / vendor category | "market analysis / competitive landscape / category map / competitor research / vendor evaluation" | _cross-/ rollups; _meta/_PRODUCT_TEMPLATE.md + _meta/_COMPARISON_TEMPLATE_.md per criterion; profile pages by default | references/industry/category-taxonomies.md, references/industry/template-authoring.md (keystone), references/industry/industry-architecture.md, references/industry/discovery.md, references/industry/evidence-and-synthesis.md, references/industry/mission-briefs.md, references/industry/profile-pages.md, references/industry/research-powerpack-and-explore.md, references/industry/worked-example-cloud-browsers.md |

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.

| | Claude subagents (default) | codex exec | |---|---|---| | Each research task is | a Claude subagent invoking run-research | a parallel codex exec subprocess writing one answer file | | Best when | fan-out ≤ ~10, interleaved multi-turn research, stylistic control | large fan-out (≥15 jobs/wave), detached burning, cheap parallel credits, explicit effort routing | | Orchestrator dispatches | subagent briefs (references/subagent-briefs.md) | one rendered prompt file per job + a bounded-concurrency loop | | Effort lever | n/a | per-wave low/medium/high via -c model_reasoning_effort= |

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/:

| Codex reference | Read when | |---|---| | references/codex/codex-exec-contract.md | Any codex dispatch — flag spine, JSON events, model/effort overrides, MCP-active fallback | | references/codex/effort-routing.md | Phase 0 — designing the per-wave low/medium/high effort plan | | references/codex/codex-prompt-skeleton.md | Waves 1-4 — the 7-section prompt each codex job receives, with input-paths / output-path / run-research block | | references/codex/wave-dispatch.md | Waves 1-4 — bounded-concurrency loop, slug rules, skip-existing, status tracking, audit gate, retry | | references/codex/orchestrator-cookbook.md | Between waves — when to read, escalate effort, fall back to a Claude subagent, declare done |

Pinned defaults

| Key | Default | |---|---| | Trigger threshold | 5+ entities, multi-axis evaluation, folder-tree output | | Executor | Claude subagents (default); codex exec when chosen at intake, or when fan-out ≥15 jobs in some wave | | Default scale | compact 5-10 entities, ~80-200 files; standard 10-40 entities, ~150-500 files; deep 40-100 entities, ~500-2000 files; tiered 100+ entities, full packs for top tier only | | Hard wave cap | 8 research tasks per wave for domain-agnostic framing; 20 per wave for industry framing | | Codex concurrency | 8 jobs/wave default; hard ceiling 32, raise only with measured justification | | Codex model / effort | gpt-5.5; per-wave low/medium/high — Wave 1 high, Wave 2 medium, Wave 3 high. See references/codex/effort-routing.md | | Recommended wave size | 6-8 tasks when integration quality or context pressure matters | | Research-task retry policy | 2 retries max per failed task, with a narrower prompt each time (codex: skip-existing, never overwrite a done answer) | | Profile pages | Default yes for core tier at standard scale or larger (industry framing); optional for domain-agnostic | | File count policy | Bounded by template-section-count × entity-count + cross-axis files. No fixed numeric cap; templates are the boundary. | | Source ledger policy | Per-entity ledgers in /09-sources/ (or 09-sources.md for compact corpora); cross-corpus ledgers in _cross-/09-sources/ |

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.

| Phase | Goal | Artifact gate | |---|---|---| | 0 — Charter | Apply intake answers; clarify decider, scale, archetype; pick framing + executor | _meta/01-charter.md scope statement + corpus scale + framing label + executor (+ effort plan if codex) | | Wave 1 — Discovery + Scope | Enumerate entities AND derive axis catalog (parallel, 2 tasks). Includes the deep category pre-pass (industry) — buyer axes, native pricing units, practitioner channels, regulatory regimes. | _meta/02-entities.md (or discovered-entities.md) + _meta/03-axes.md + category-understanding note | | 2 — Template authoring | Write maximalist _meta/04-product-template.md + _meta/05-axis-templates.md (domain-agnostic) OR _meta/_PRODUCT_TEMPLATE.md + per-criterion _meta/_COMPARISON_TEMPLATE_.md (industry). Templates set the comprehensiveness boundary. | Templates locked AND shown to the user | | 3 — Architecture | Plan tree shape, MAX-N caps, entity tiers, file-count expectation derived from templates. Optionally scaffold via scripts/init-corpus.sh. | _meta/06-file-budget.md / _meta/file-budget.md | | Wave 2 — Per-entity packs | Fill / for every core entity (parallel, ≤8 per sub-wave domain-agnostic; ≤20 per sub-wave industry). Each task owns one folder; write scopes disjoint. Each invokes run-research. | Populated / folders; every template section addressed (content OR explicit "insufficient evidence" entry naming the data gap) | | Wave 3 — Per-axis cross synthesis | Compare entities along each axis. LOCAL-ONLY (no web tools). Each task owns one cross folder. | Populated _cross// or _cross-/ folders with ranking + matrix + decision-flippers | | Wave 4 (optional) — Profile pages OR promoted research | Standalone .md decision pages at corpus root (LOCAL-ONLY) OR additional research packs for promoted entities (web-capable, invokes run-research) | Profile pages OR new entity packs | | 7 — Verification + Master summary | Orchestrator personally reads every file. Resolves contradictions. Writes _meta/00-master-summary.md. Runs verification gate. | _meta/00-master-summary.md + verification log; template-coverage audit passes |

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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yigitkonur
• Source: yigitkonur/skills-by-yigitkonur
• License: MIT

Install and usage instructions live in the source repository linked above.