/web-research

name: web-research
description: "Use when the user wants web research: gathering cited, multi-angle evidence on a specific question. Triggers on: \"research X for me\", \"do web research on\", \"look up sources for\", \"find citations for\", \"gather evidence on\", \"what does the web say about X\". Also invoked programmatically by other beagle skills (prfaq-beagle Ignition, brainstorm-beagle reference points, strategy-interview context grounding) via the companion contract. Does NOT trigger on codebase lookups (\"find this function\", \"search the repo\"), local file search, LLM-as-judge evaluation, or paywalled/auth-gated scraping. Produces a written plan, parallel-subagent findings, and a cited synthesis report on disk — never inline prose, never unsourced claims."

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](../artifact-analysis/SKILL.md).
• Comparative evaluation of two implementations. Use [llm-judge](../llm-judge/SKILL.md).
• 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.”

| Gate | Blocks | Pass condition | | --- | --- | --- | | **G0 — Tools** | Slug derivation, `output_dir`, any write | web search (if web access is available) works. On fail: emit JSON per `references/failure-modes.md` (“Fail-fast on missing web tools”); **do not** create `plan.md` or any other artifact. | | **G1 — Re-run** | First write under `output_dir` | `output_dir` has no `plan.md` or `report.md`, **or** `refresh: true` with prior contents archived per “Re-run protection” in `references/failure-modes.md`. | | **G2 — Plan artifact** | Subagent dispatch | `plan.md` exists and includes every required bullet under “The research plan (`plan.md`)”. | | **G3 — Review** | Dispatch | User has confirmed the plan **or** `auto_proceed: true`. | | **G4 — Findings set** | Synthesis | For each subtopic in `plan.md`, `findings/<slug>.md` exists and has `status:` frontmatter (stub allowed). | | **G5 — Deliverable** | Success return to caller | `report.md` exists; end-of-run checklist in `references/failure-modes.md` (“Verification checklist”) is satisfied **or** each failed check is recorded under `Gaps & Limitations`. |

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:

| Field | Type | Required | Default | Purpose | | ------------------- | ----------------- | -------- | ------- | -------------------------------------------------------------------- | | `research_question` | string | yes | — | The question to answer, already distilled. The skill does not reshape it. | | `output_dir` | absolute path | no | derived | Where plan.md, findings/, and report.md land. | | `auto_proceed` | bool | no | `false` | When true, skip the plan review gate and dispatch immediately. | | `refresh` | bool | no | `false` | When true, allow overwriting a prior run in the same `output_dir`. |