web-research

What this skill does

# 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`.   |

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 rev