existential-birds/beagle / plugins/beagle-analysis/skills/web-research
web-research
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.2 KB |
| references/citation-schema.md | markdown | 3.0 KB |
| references/companion-contract.md | markdown | 6.0 KB |
| references/failure-modes.md | markdown | 4.7 KB |
| references/report-template.md | markdown | 3.0 KB |
| references/subagent-brief.md | markdown | 3.1 KB |
references/companion-contract.md
View on GitHub# 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
```yaml
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
```yaml
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
```yaml
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)
```yaml
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)
```yaml
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`:
```yaml
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:
```yaml
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`:
```yaml
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |