Web Research

Web Research

Turn a sharp research question into cited, gap-flagged findings by delegating to parallel web-search subagents.

The deliverable is always on disk: a written plan the caller can review, one findings file per subtopic, and a synthesized report with numbered citations. Nothing returns as inline prose, and no claim ships without a URL + title + verbatim excerpt behind it.

When to use

• A user asks for web research on a topic — "research X", "look up sources for Y", "gather evidence on Z".
• Another beagle skill invokes this one programmatically as a research companion (see references/companion-contract.md).
• The caller wants auditable output: a plan the user approved, findings files per subtopic, and a citation-backed synthesis.

When NOT to use

• Codebase lookups ("where is this function defined", "search the repo"). Search the codebase instead.
• Local file search or document extraction. Use local file search or artifact-analysis.
• Comparative evaluation of two implementations. Use llm-judge.
• Paywalled or authentication-gated scraping. Out of scope — ask the caller to paste extracted content instead.
• Reshaping or coaching the research question. That is the caller's job; this skill treats the incoming question as final.

Workflow

Four steps, in order. No step is skippable.

1. Write `plan.md` — main question verbatim, 1-5 non-overlapping subtopics, what each subtopic should establish, and how the findings will be synthesized. 2. Plan review gate — show the plan to the user for confirmation. Skipped only when the caller passes auto_proceed: true. 3. Dispatch subagents and synthesize — spawn up to 3 concurrent subagents (one per subtopic), wait for all to return, then write report.md. 4. Verify before returning — run the verification checklist in references/failure-modes.md to confirm all expected artifacts exist and are well-formed. Any check that fails becomes an entry in Gaps & Limitations.

Hard gates (objective pass conditions)

Advance only when the prior gate passes. A pass is always evidenced by a file on disk, a caller flag, or a structured error — not an internal “I checked.”

Receive question ──→ Write plan.md ──→ Review gate (unless auto_proceed)
                                      ↓
                                    User confirms
                                      ↓
                                    Dispatch subagents (up to 3 parallel)
                                      ↓
                                    Collect findings/<slug>.md files
                                      ↓
                                    Synthesize report.md
                                      ↓
                                    Return paths to caller

Before step 1, verify the environment has web search (if web access is available). Page fetch is desirable for subagents that need full-page content beyond search snippets, but not required — search-only environments can still produce useful findings. If web search is absent, fail fast per references/failure-modes.md — do not create plan.md, do not spawn subagents.

Inputs

The input contract is small and strict:

The skill does not parse caller-specific structures. Callers distill their brief into one sharp question string before invoking.

When to pass `auto_proceed: true` vs `false`. Pass false (the default) when the user will still benefit from seeing the subtopic plan before searches burn — e.g. the caller wants this skill's plan-review gate to serve as that check. Pass true when the caller has already satisfied the "is this the right framing" question through its own interaction with the user, and another gate would just be friction — e.g. the user explicitly asked mid-conversation for background research, or the caller runs its own review loop upstream. The rule is about where the review happens, not whether it happens.

Output location

If the caller provides output_dir, use it verbatim. Otherwise derive the default:

.beagle/research/<YYYY-MM-DD>-<topic-kebab>/

Slug derivation (stable so re-running the same question on the same day lands on the same folder):

1. Take the research question. 2. Lowercase. 3. Strip punctuation (keep letters, digits, spaces, hyphens). 4. Collapse runs of whitespace to single hyphens. 5. Truncate to 60 characters on a word boundary (cut at the last hyphen before 60). If there is no hyphen before position 60, hard-cut at 60. 6. Prepend YYYY-MM-DD-.

Re-run protection. Before writing anything, check whether output_dir already contains plan.md or report.md. If it does and refresh is not true, refuse with a message naming the existing folder. When refresh: true, archive the prior contents into <output_dir>/.archive-<timestamp>/ first, then start fresh. See references/failure-modes.md and references/companion-contract.md.

Every run lands in its own folder so callers weeks later can re-read the plan, findings, and report without re-running the skill.

The research plan (plan.md)

The plan is written before any subagents run and is the caller's chance to catch bad framing before searches burn.

plan.md contains:

• Research question — the input string, verbatim.
• Subtopics — 1 to 5, non-overlapping, each with a one-line name.
• What each subtopic should establish — concrete bullets, not "research everything about X".
• Synthesis approach — how the subtopics' findings will combine into report.md.
• Budget — how many subagents will spawn and how many searches each has (see Budget defaults below).

Plan review gate. By default, show plan.md to the user and wait for confirmation before dispatching. The user can revise subtopics, add or remove them, or reject the framing entirely. When the caller passes auto_proceed: true, skip the gate and dispatch immediately — this is the programmatic-companion path where the caller has its own review loop.

Subagent dispatch

Up to 3 subagents run concurrently. Each gets a mechanically-derived brief built from plan.md — no interpretation drift between the plan the user approved and the briefs the subagents received. The brief template lives in references/subagent-brief.md.

Each subagent:

• Runs its budgeted web searches (3-5 by default).
• Writes findings/<subtopic-slug>.md under output_dir.
• Returns one terse status line to the orchestrator (path + status), never inline findings.

The orchestrator waits for all subagents to finish, then verifies every expected findings file exists before moving to synthesis. A missing file is a silent failure, recorded in Gaps & Limitations — see references/failure-modes.md.

See references/subagent-brief.md for the full brief shape and the required frontmatter on each findings file.

Citations

Every claim in a findings file and in report.md carries a citation. The shape is documented in references/citation-schema.md. At a glance:

• Required fields: url, title, excerpt (verbatim quote from the page).
• Optional fields: retrieved_at (ISO date), source_type (official-docs / vendor / blog / forum / news / other).
• Never synthesize missing metadata. If the subagent does not have a retrieval date, omit the field — do not fabricate one.

Inline references use [^n] footnotes; the full citation sits in the numbered Sources section at the bottom of the report.

Synthesis (report.md)

The report has a fixed four-section layout, in this order. Every section is required, every time.

1. ## TL;DR — 3-5 bullets capturing the highest-signal findings. 2. ## Findings — organized by subtopic or theme; every claim carries a [^n] footnote. 3. ## Gaps & Limitations — what the research could not establish, including any failed subagents. 4. ## Sources — numbered bibliography matching footnote numbers.

Gaps & Limitations is required even when findings look complete. Honest accounting of what was and was not verifiable is part of the product. The full literal skeleton the skill copies from lives in references/report-template.md.

Failure modes

• Partial success — one or more subagents fail. The skill continues with what succeeded and enumerates each failed subtopic under Gaps & Limitations, including the last-known brief and the stub-file reason. The run does not abort.
• Fail-fast — web search (if web access is available) unavailable. Abort before any disk write (including plan.md); return structured JSON per references/failure-modes.md. Page fetch is optional for subagents and is not part of this gate.
• Silent-failure detection — every subagent writes at least a stub findings/<slug>.md with status: frontmatter (ok, empty, failed) before returning. Missing file after dispatch = silent failure, recorded in Gaps & Limitations.
• Re-run protection — covered under "Output location" above; details in references/failure-modes.md.

Full rules and the structured error shape live in references/failure-modes.md.

Budget defaults

Tunable knobs, not hard-coded invariants:

A caller that needs broader or narrower scope can override via the brief. The plan-review gate is the right place to adjust before searches burn.

Companion invocation contract

Other beagle skills invoke this one via a small, documented contract. The minimal call passes only research_question; the full call adds output_dir, auto_proceed, and refresh.

Worked examples for the three known callers (prfaq-beagle, brainstorm-beagle, strategy-interview) plus the success and fail-fast return shapes live in references/companion-contract.md. Callers are expected to honor the contract verbatim rather than invent parallel invocation styles.

Tone

This skill is a tone-neutral primitive. It does not:

• Coach the caller on whether the question is the right one.
• Reshape, sharpen, or challenge the research question.
• Adopt a posture (hardcore, Socratic, warm) — that is the caller's job.
• Editorialize in findings or the report.

If the caller is a coaching skill (prfaq-beagle, brainstorm-beagle), the coaching happens before and after this skill runs. Inside this skill, the question is treated as final.

Out of scope

• Long-running or scheduled research jobs.
• LLM-as-judge evaluation of source credibility — llm-judge already covers comparative evaluation.
• Scraping paywalled or authentication-gated sources.
• Coaching, challenge, or opinionated reshaping of the research question.
• Multi-language research.
• Caching or de-duplication of findings across invocations.
• Non-web research modes (local files, project docs, databases) — use artifact-analysis.

Reference files

• references/subagent-brief.md — template the orchestrator mechanically fills from plan.md when dispatching each subagent.
• references/citation-schema.md — required and optional citation fields, footnote convention, and a well-formed example.
• references/report-template.md — literal report.md skeleton with all four fixed sections.
• references/failure-modes.md — partial-success, fail-fast, silent-failure detection, and re-run protection rules.
• references/companion-contract.md — programmatic invocation shape with worked examples for prfaq-beagle, brainstorm-beagle, and strategy-interview.

Citation Schema

Every claim in a findings file and in report.md carries a citation. The shape is small on purpose — enough metadata to verify without clicking, not so much that subagents start fabricating fields.

Required fields

• `url` — the exact page the claim was drawn from. No redirectors, no homepage-in-place-of-article substitutions.
• `title` — the page's own title, as rendered (not the domain, not a paraphrase).
• `excerpt` — a verbatim quoted string from the page that supports the claim. Keep it short enough to read at a glance (typically 1-3 sentences), long enough to stand on its own.

If any required field is missing or would have to be fabricated, do not include the citation. Drop the claim or mark it as unverified in Gaps & Limitations.

Optional fields

Include only when the subagent naturally has them. Never synthesize.

• `retrieved_at` — ISO date (YYYY-MM-DD) the page was fetched. Useful for time-sensitive claims (pricing, availability, current events).
• `source_type` — one of:
• official-docs — vendor/project documentation.
• vendor — vendor marketing, press, or blog under the vendor's own domain.
• blog — third-party blog or personal site.
• forum — discussion board, Q&A site, mailing list archive.
• news — press coverage from a recognized news outlet.
• other — anything that doesn't fit (academic paper, standards body, regulator filing).

Omit fields you do not have. An incomplete citation with three real fields beats a five-field citation with two guessed values.

Footnote convention

In findings and in report.md, claims use [^n] inline footnote markers:

Pricing for the enterprise tier starts at $20k/year with a 25-seat minimum[^3].

The numbered Sources section at the bottom of report.md lists each citation in order, matching the footnote number. Numbering is global across the report, not per-section.

Example — well-formed citation block

In report.md, the Sources section entries look like this:

[^1]: **Title**: Enterprise Pricing — Acme Docs
      **URL**: https://docs.acme.example/pricing/enterprise
      **Excerpt**: "Enterprise plans start at $20,000 per year and require a 25-seat minimum commitment."
      **Retrieved**: 2026-04-18
      **Source type**: official-docs

[^2]: **Title**: Acme raises Series C at $2B valuation
      **URL**: https://news.example/acme-series-c
      **Excerpt**: "The round, led by Example Partners, brings total funding to $340M."
      **Source type**: news

Citation [^2] omits Retrieved because the subagent did not record a retrieval date. That is correct behavior — omit rather than guess.

Incomplete-metadata policy

If a claim is genuinely load-bearing but the source lacks one of the optional fields (e.g. a news article without a clear publication date), keep the citation with what exists. If a claim depends on freshness and no retrieval date is available, note the uncertainty in Gaps & Limitations rather than citing confidently.

Companion Invocation Contract

Other beagle skills invoke web-research via this contract. It is small on purpose — one required input, three optional parameters, three return shapes.

Callers are expected to honor the contract verbatim rather than invent parallel invocation styles. If a new caller needs behavior that the contract does not support, extend the contract here first, not in the calling skill.

Minimal call

research_question: "How do enterprise observability vendors price their logs tier in 2026?"

The skill derives output_dir as .beagle/research/<YYYY-MM-DD>-<topic-kebab>/ per the slug rule in SKILL.md, runs the plan review gate (default auto_proceed: false), and refuses if a prior run exists in the same folder (default refresh: false).

Full call

research_question: "How do enterprise observability vendors price their logs tier in 2026?"
output_dir: "/abs/path/to/output"
auto_proceed: false
refresh: false

Input semantics

• `research_question` — one sharp question, already distilled by the caller. The skill does not reshape it. If the caller has a multi-part question, pick the single most important one; the skill's subtopics will break it down.
• `output_dir` — absolute path. If the caller wants artifacts next to its own work (e.g. under .beagle/concepts/<slug>/research/), it sets this explicitly.
• `auto_proceed` — when true, the plan review gate is skipped and dispatch happens immediately. Use this in programmatic-companion paths where the caller has its own review loop.
• `refresh` — when true, a prior run in output_dir is archived to <output_dir>/.archive-<timestamp>/ before the new run starts. See failure-modes.md for the archive rule.

Return shapes

This skill returns one of three shapes. Callers that invoke multiple beagle companions should handle the union of error codes across all companions they call — sibling companions (e.g. artifact-analysis) may return different error codes.

• success — all artifacts written.
• error: `web-tools-unavailable` — missing WebSearch; nothing written.
• error: `prior-run-present` — output_dir already holds a prior run and refresh is false; nothing written.

Success

plan: "<output_dir>/plan.md"
report: "<output_dir>/report.md"
findings_dir: "<output_dir>/findings/"

The caller receives absolute paths. All evidence lives on disk — nothing returns inline.

Fail-fast (web tools unavailable)

error: "web-tools-unavailable"
detail: "missing: WebSearch, WebFetch"

The caller catches this and triggers its own graceful-degradation path. No files are written in this case — not even plan.md.

Refused (prior run present, no refresh)

error: "prior-run-present"
detail: "<output_dir> already contains plan.md or report.md. Pass refresh: true to archive and overwrite."

The caller decides whether to retry with refresh: true, pick a different output_dir, or surface the refusal to its user.

Worked examples

prfaq-beagle — Ignition grounding

The PRFAQ's Ignition phase needs competitive and market grounding. PRFAQ distills the ambiguity into one research question, then calls web-research:

research_question: "What AI coding-assistant pricing tiers exist for enterprise teams in 2026, and what features differentiate them?"
output_dir: "/abs/path/.beagle/concepts/ai-coding-pricing/research/"
auto_proceed: false
refresh: false

auto_proceed: false because the user is in the PRFAQ loop and wants to see the research plan before subagents run. output_dir lands inside the PRFAQ concept folder so the audit trail travels with the concept.

brainstorm-beagle — reference-point research

Mid-brainstorm, the user says "go look up how other tools handle this." Brainstorm calls web-research with the user's question distilled:

research_question: "How do task-tracking tools handle sub-tasks that span multiple top-level projects?"
output_dir: "/abs/path/.beagle/concepts/task-sub-tasks/research/"
auto_proceed: true
refresh: false

auto_proceed: true because the user explicitly asked for background research mid-brainstorm — they want findings, not another review gate. output_dir lands inside the brainstorm concept folder so the spec's reference points can link straight to report.md.

strategy-interview — context grounding

During strategy interview Phase 1 discovery, the user needs competitive landscape data. Strategy-interview calls web-research:

research_question: "Which incumbents dominate the developer-tools observability market, and what is their defensibility story?"
output_dir: "/abs/path/.beagle/strategy/platform-team-h1-2026/research/"
auto_proceed: false
refresh: false

auto_proceed: false because the strategy interview benefits from the user catching bad subtopic framing before searches burn. output_dir lands inside the strategy interview's working-state folder so the research sits alongside state.md, evidence.md, and composition.md.

Non-obligations

The contract is explicit about what this skill does not do:

• No question reshaping. The caller hands in a sharp question. If the caller has a fuzzy question, the caller sharpens it before invoking.
• No coaching posture. web-research is tone-neutral. Callers that need a coaching tone (prfaq-beagle's hardcore coach, brainstorm-beagle's thinking partner) apply that tone before and after, not inside.
• No inline findings. Every deliverable is a file. Callers that want inline prose should summarize from report.md themselves.
• No cross-run caching. Each invocation stands alone. Callers that need caching build it themselves at the call site.

Extending the contract

If a new caller needs behavior not covered here, add a field to the input table in SKILL.md first, document it in this file with a worked example, then update caller skills to use it. Parallel-invocation styles fragment the contract and re-introduce the reason this skill exists.

Failure Modes

Four failure cases the skill handles explicitly. Silent failures are the worst kind — every rule below exists to make a failure visible to the caller and preserve what succeeded.

Partial success

One or more subagents fail; others return valid findings.

Behavior: continue with the successful findings. Do not abort the run.

In the synthesis file, under Gaps & Limitations, enumerate every failed subtopic:

• Name the subtopic.
• Include the subagent's last-known brief (or a one-line summary of what it was asked to establish).
• Include the reason line from the stub findings file (see "Silent-failure detection" below).

Example:

## Gaps & Limitations

- **Subtopic "Enterprise pricing history"** (status: failed) — subagent returned "page-fetch timeout after 3 retries on docs.acme.example/pricing". Caller may retry this subtopic alone, or re-run with `refresh: true` after the outage clears.

Fail-fast on missing web tools

Web search is the core capability for this skill. If web search (web access) is not available in the environment, the skill aborts before spawning any subagent. It also does not write plan.md — nothing lands on disk.

Page fetch is desirable for subagents that want full-page content beyond search snippets, but not required. Search-only environments can still produce useful findings; each subagent notes in its findings file any claim it would have strengthened with full-page access.

Return shape (structured so parent skills can detect and branch):

{
  "error": "web-tools-unavailable",
  "detail": "missing: WebSearch"
}

Parent skills (prfaq-beagle, brainstorm-beagle, strategy-interview) catch this and trigger their own graceful-degradation path — typically asking the user to paste research findings instead.

Verification runs at the very start of the skill, before slug derivation and before any file I/O.

Silent-failure detection (stub-file rule)

Context exhaustion and tool errors can cause a subagent to return without producing any output file. The orchestrator has no way to distinguish that from "the subagent finished but the file is missing for some other reason" — so the contract requires every subagent to write at least a stub file before returning.

Contract (enforced by `subagent-brief.md`):

• Every subagent writes findings/<subtopic-slug>.md with a status: frontmatter field: ok, empty, or failed.
• On empty or failed, the file includes a one-line reason: field.
• On ok, reason is omitted.

Orchestrator check, post-dispatch:

For every expected subtopic, test that the findings file exists. For any missing file, record a silent-failure entry under Gaps & Limitations:

- **Subtopic "<name>"** — subagent returned without producing a findings file (likely context exhaustion or tool error). Last known brief: "<brief summary>".

This is why "legitimately empty" results must use status: empty with a reason rather than writing nothing — so empty-but-ok is never confused with silent context loss.

Re-run protection

Each run is supposed to be self-contained and auditable. Silently overwriting a prior run destroys the audit trail; silently appending produces incoherent findings.

Rule: before writing anything to output_dir, check whether it already contains plan.md or report.md.

• If it does and `refresh` is not `true`: refuse with a message naming the existing folder.

  Refusing to write: <output_dir> already contains a prior research run. Pass `refresh: true` to archive and overwrite, or choose a different output_dir.

• If it does and `refresh: true`: move the existing contents to <output_dir>/.archive-<YYYYMMDD-HHMMSS>/ first, then proceed with a fresh run. The archive preserves the audit trail.

• If it does not: proceed normally.

This rule applies even when the default slug matches a prior run on the same day — stable slugs are a feature (callers can re-derive the folder), but the user must explicitly opt in to overwriting.

Verification checklist (orchestrator runs at end)

Before returning success to the caller, verify:

• [ ] plan.md exists at <output_dir>/plan.md.
• [ ] findings/<slug>.md exists for every subtopic in plan.md.
• [ ] Every findings file has status: frontmatter.
• [ ] Every status: empty or status: failed file has a reason: line.
• [ ] report.md exists at <output_dir>/report.md.
• [ ] report.md has all four top-level sections in order: TL;DR, Findings, Gaps & Limitations, Sources.
• [ ] Every [^n] footnote in report.md has a matching entry in Sources.

Any check that fails becomes an entry in Gaps & Limitations — the run does not silently produce a broken deliverable.

Synthesis Skeleton

The synthesis document, saved as report.md under the run's output directory, uses a fixed four-section layout. Sections appear in this order, every time, even when one is short. Gaps & Limitations is required even when findings look complete — honest accounting of what could not be established is part of the product.

Copy the skeleton below into the synthesis file and fill each section.

Layout

# Research: <research question, verbatim from plan.md>

## TL;DR

- <3 to 5 bullets, highest-signal findings first>
- <each bullet stands alone — a reader should grasp the answer without scrolling further>
- <cite with [^n] when a bullet makes a specific factual claim>

## Findings

### <Subtopic or theme 1>

<Paragraphs or bullets. Every factual claim carries a [^n] footnote. Group claims by subtopic or by theme that cuts across subtopics — choose whichever reads better for this question.>

### <Subtopic or theme 2>

<...>

### <Subtopic or theme N>

<...>

## Gaps & Limitations

- <What the research could not establish, and why. One bullet per gap.>
- <Any subagent that failed or returned empty — name the subtopic and the reason from its stub file.>
- <Claims that required a freshness check (retrieval date) but were not time-stamped.>
- <Questions that surfaced during research but were out of scope for this run.>

## Sources

[^1]: **Title**: <page title>
      **URL**: <url>
      **Excerpt**: "<verbatim quote>"
      **Retrieved**: <YYYY-MM-DD, omit if absent>
      **Source type**: <official-docs | vendor | blog | forum | news | other, omit if absent>

[^2]: **Title**: <...>
      **URL**: <...>
      **Excerpt**: "<...>"

[^n]: <...>

Rules

• Title line reproduces the research question verbatim from plan.md. Do not paraphrase.
• `TL;DR` is 3-5 bullets. Not 1, not 10. If only one thing is worth saying, the research is thin — flag it in Gaps & Limitations.
• `Findings` groups by subtopic by default. If a cross-cutting theme reads better, use that instead, but keep every claim footnoted. Structure serves the reader.
• `Gaps & Limitations` is never empty. At minimum, include what future work would sharpen the answer. When subagents fail, each failed subtopic gets its own bullet with the subtopic name and the reason from its stub file (see failure-modes.md).
• `Sources` uses global numbering — [^1] through [^n] across the whole document, not per-section. Citation shape per citation-schema.md.

Sourcing discipline

• Every bullet in TL;DR that makes a specific factual claim carries a footnote. Broad synthesis statements ("the market is split between two approaches") can stand without a footnote if they summarize cited claims in Findings.
• Inside Findings, no unsourced claims. If a claim cannot be cited, either drop it or move it to Gaps & Limitations as something the research could not establish.
• Sources entries match every [^n] used in TL;DR and Findings. Orphan citations (listed in Sources but never referenced) should be removed.

Subagent Brief Template

The orchestrator builds one brief per subtopic, mechanically, from plan.md. Every subagent gets the same shape so a caller reading plan.md can predict what each subagent was told.

Fill the template verbatim — no paraphrasing, no interpretation drift. Subagents return one terse status line to the orchestrator; all findings land in the output file.

Template

You are one of up to 3 parallel research subagents. Investigate a single subtopic and write findings to disk.

Subtopic: <subtopic name, copied from plan.md>
Research question: <main research_question, verbatim from plan.md>
What to establish:
- <bullet 1 from plan.md for this subtopic>
- <bullet 2 from plan.md for this subtopic>
- <...>
Budget: up to <N> web searches. Write exactly one findings file. Do not return findings inline.
Output path: <output_dir>/findings/<subtopic-slug>.md

Citation rules: every claim carries a `[^n]` footnote. Citations use URL + page title + verbatim excerpt; add retrieved_at and source_type only when the source naturally provides them. See references/citation-schema.md for the full shape.

Required frontmatter on the output file:
---
status: ok | empty | failed
subtopic: <subtopic name>
brief_hash: <hash of this brief, supplied by the orchestrator>
started_at: <ISO timestamp>
finished_at: <ISO timestamp>
reason: <one line — required when status is empty or failed, omit otherwise>
---

Partial-failure protocol: always write the output file, even if the subagent fails or finds nothing. Use status: failed with a one-line reason on tool errors or exhaustion. Use status: empty with a reason when the topic is legitimately unsearchable ("no public sources found for <specific claim>"). Never exit without writing the file — absence of the file is treated as a silent failure.

Return: a single status line in this exact shape, and nothing else:
<path-to-findings-file> <status>

Example: /abs/path/findings/pricing-models.md ok

Orchestrator responsibilities

• Build `<subtopic-slug>` by the same rule as the research-question slug in SKILL.md (lowercase, punctuation stripped, whitespace to hyphens, truncated to 60 chars on a word boundary). Keep it stable across runs so refresh: true can match archived prior files.
• Compute `brief_hash` over the filled-in brief text before dispatch so the findings file's provenance is verifiable.
• Verify every expected file exists after all subagents return. Any missing file = silent failure per failure-modes.md.
• Never merge findings into one file. Synthesis happens later, in report.md.

Subagent responsibilities

• Write the output file even on failure. Absence is treated as silent context exhaustion.
• Do not reshape the subtopic or the research question. If the brief is wrong, flag it in reason and return status: failed — do not silently pivot to a different question.
• Cap the budget. Stop at N searches. More searches without new signal means the subtopic is saturated; write what you have with status: ok.
• No inline returns. The only thing that crosses back to the orchestrator is the status line. All evidence lives in the findings file.