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"). Use Grep/Glob.
• Local file search or document extraction. Use the file tools 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.”

| Gate | Blocks | Pass condition | | --- | --- | --- | | G0 — Tools | Slug derivation, output_dir, any write | WebSearch (or equivalent) is available. 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 WebSearch (or equivalent). WebFetch is desirable for subagents that need full-page content beyond search snippets, but not required — WebSearch-only environments can still produce useful findings. If WebSearch 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. |

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 me