references/fetch-content.md
# Content and repository retrieval guidance
Read this before retrieving multiple sources, repositories, PDFs, or truncated result content.
## Choose the available capability
Tool names and schemas vary. Inspect the runtime and choose the available capability for direct URL extraction, repository access, document parsing, stored-result retrieval, or browser-backed fallback. Prefer the narrowest tool that can obtain the required evidence.
## Standard pages and documentation
- Retrieve the user-provided URL directly before searching for summaries of it.
- For several sources, fetch only the selected answer-critical pages rather than every search result.
- Preserve source URLs and note publication/update dates or versions when material.
- If extraction omits important content, try the tool's full-content/stored-result mode, an alternate extractor, repository access, or browser automation.
## Source repositories
- Use repository-aware retrieval or a local clone when implementation details matter.
- After retrieval, inspect relevant source, tests, examples, docs, release tags, and history with normal file/search tools.
- Check for an existing local clone before creating another; update it safely when freshness matters.
- Do not force a full clone of a very large repository unless targeted API/file access is insufficient.
- Cite stable source links or commit identifiers when explaining implementation details.
## PDFs and documents
- Use text extraction when the question concerns prose or searchable facts.
- Use document search to locate known phrases and page positions.
- Use page screenshots when charts, tables, diagrams, signatures, or layout affect the answer.
- Keep visual inspection to the smallest relevant page range unless broader coverage is requested.
## Truncated or blocked content
- Retrieve the stored/full result when the tool supports it.
- Narrow retrieval to one result, URL, page range, file, or repository path.
- For JavaScript-heavy or blocked pages, try another extraction path or browser automation.
- Record inaccessible sources and avoid claiming details that were visible only in a search snippet.
## Safety
- Do not retrieve or persist secrets, private session state, or unnecessary sensitive content.
- Treat repository scripts and downloaded artifacts as untrusted; reading does not require executing them.
- For private sources, use only user-authorized access and avoid copying sensitive content into durable research notes.
references/web-search.md
# Web search guidance
Read this before complex discovery, multi-angle research, source filtering, or recency-sensitive searches.
## Choose the available capability
Tool names and schemas vary. Inspect the current runtime and choose a search capability that supports the needed combination of web discovery, domain targeting, recency, result breadth, and source links. Do not assume a specific function or provider exists.
## Query strategy
- Use two to four meaningfully different search angles for substantive research.
- Useful angles include official documentation, release notes/changelogs, source implementations, standards, first-party examples, and independent analysis.
- Avoid near-duplicate rephrasings that return the same result set.
- Use domain inclusion/exclusion, recency, language, or result-count controls when available and relevant.
- Prefer search-first discovery, then retrieve only answer-critical sources. Do not broadly fetch every result by default.
- For code questions, include the exact library/framework version and search official docs, source repositories, issues, and release history.
## Source triage
Prioritize results that are:
1. Primary and authoritative.
2. Version/date matched.
3. Directly relevant to the exact behavior or decision.
4. Detailed enough to inspect rather than only summarize.
5. Corroborated when the claim is security-, compatibility-, or implementation-critical.
Treat generated summaries, snippets, scraped mirrors, and unsourced posts as leads rather than final evidence.
## Failure recovery
- Weak results: vary the angle, narrow to official domains, add version identifiers, or search source/release history directly.
- No primary source: inspect the vendor repository, standards body, changelog, release notes, or implementation tests.
- Conflicting sources: prefer version-matched official docs/source and record the disagreement.
- Search tool unavailable: use known authoritative URLs, repository access, local package/source inspection, or another available discovery capability and state the limitation.
SKILL.md
---
name: web-research
description: Researches current web and external technical information through source-backed discovery, retrieval, and repository, document, or media inspection. Use this skill when the user needs current facts, docs, articles, URLs, repositories, PDFs, videos, comparisons, or version-specific library/API/framework evidence. Do not use this skill alone for interactive browser tasks such as login, forms, or UI-state inspection; use an available browser automation capability.
license: MIT
compatibility: >-
Requires at least one current search, content-retrieval, repository, document,
or media capability appropriate to the task. Interactive login, form, or UI
state workflows additionally require an available browser automation
capability.
metadata:
short-description: Research current web, code, repository, document, and media evidence
---
# Web Research
## Instruction priority
Follow explicit user constraints and higher-priority instructions. If the user narrows scope, forbids external tools, requests chat-only output, or changes this workflow, adapt and briefly note meaningful deviations.
Use the best currently available search, content-retrieval, repository, document, media, and browser capabilities. Tool names and schemas differ between runtimes: inspect the available tools instead of assuming a particular function name.
## Core rules
- For substantive multi-source, conflicting, resumable, implementation-critical, or high-risk research, create or reuse `.progress/<research-slug>.md` early for questions, context, search angles, sources, findings, conflicts, rejected evidence, open questions, and synthesis decisions.
- Small direct lookups or source reads do not require a progress artifact. Preserve answer-critical sources and findings in the response.
- When progress notes exist, reread them before final responses, handoffs, compaction summaries, or user-requested summaries.
- Prefer primary sources: official docs, source repositories, release notes, changelogs, standards, vendor announcements, and first-party data.
- Read answer-critical source content. Search snippets and generated summaries are discovery aids, not sufficient evidence for behavior-sensitive claims.
- Continue with targeted follow-up when evidence is incomplete, ambiguous, outdated, conflicting, version-mismatched, or available only from weak secondary sources.
- For code/dependency research, identify the exact installed or targeted version from project files before judging behavior. Record runtime, adapter, framework, and integration boundaries that could affect the answer.
- For signatures, hashing, serialization, canonicalization, authentication, or wire protocols, require an independent official implementation, test vector, or interoperability check; a self-consistent round trip is not enough.
- Stop when material questions are supported, remaining gaps are explicitly non-material, or further useful evidence is unlikely.
- Cite source URLs clearly and state uncertainty instead of guessing.
- Never store secrets, credentials, private session data, or sensitive source content in research notes.
## Resource routing
| Need | Guidance |
|---|---|
| Discover or compare sources | Use an available web search capability; read `references/web-search.md` before complex, filtered, multi-angle, or recency-sensitive discovery. |
| Inspect URLs, docs, repositories, or PDFs | Use an available content/repository/document retrieval capability; read `references/fetch-content.md` before multi-source, repository, PDF, or truncated-content work. |
| Analyze video/audio or visual moments | Use an available media-capable retrieval/analysis tool and pass the user's exact question; read `references/media.md` first. |
| Interact with login, forms, pagination, dynamic UI, or authenticated state | Use an available browser automation capability rather than static search/retrieval alone. |
| Inspect local documents | Use an available local document parser/search/screenshot capability, choosing text extraction or visual inspection according to the question. |
## Workflow
1. **Classify the task and create proportional research memory**
- Classify it as a small direct lookup/source read or as substantive multi-source, conflicting, resumable, implementation-critical, or high-risk research.
- For substantive research, create or reuse `.progress/<research-slug>.md` and record the question, intended output, constraints, evidence bar, known context, and search angles.
- For a small lookup, work directly and retain answer-critical sources and findings for the response.
2. **Establish exact technical context when applicable**
- Identify dependency/library/framework names and versions from manifests, lockfiles, imports, config, or installed metadata.
- Record relevant runtime, platform, adapter, environment, and compatibility constraints.
- List implementation-critical questions: normal behavior, edge cases, error semantics, migration constraints, and integration boundaries.
3. **Discover sources deliberately**
- If the user supplied a public source, inspect it directly before searching broadly.
- Otherwise search from two to four meaningfully different angles: official documentation, source/release history, implementation examples, and independent corroboration.
- Prefer focused search and selected retrieval over indiscriminate background fetching.
4. **Retrieve and inspect primary evidence**
- Read the actual official docs, source files, release notes, standards, repository examples, PDFs, or media needed for the answer.
- For repositories, inspect implementation and tests when behavior matters; README-level claims alone may be insufficient.
- Retrieve full stored content or use another retrieval path when results are truncated.
- For substantive research, record useful, weak, stale, conflicting, and rejected sources in progress memory.
5. **Evaluate sufficiency and follow up**
- Check authority, date/version match, directness, agreement, edge cases, failure behavior, and implementation implications.
- Resolve conflicts by preferring version-matched official docs and source, then release notes/changelogs, first-party examples, and finally secondary analysis.
- Continue only with targeted follow-up; avoid redundant research once strong sources converge.
6. **Synthesize carefully**
- State the supported answer, version constraints, implementation implications, and meaningful uncertainty.
- Separate observed facts from inference and explain material conflicts.
- Do not expose tool mechanics unless they matter to the user.
## Late results
If delayed research output arrives after an answer, re-engage only when it materially changes the conclusion, reveals an important correction, or the user asks about it.