Skip to content

nledford/engineering-review-board / skills/donsetch-web-research

donsetch-web-research

Verified

Use the DonSeTch MCP server for public web research, source discovery, URL or PDF retrieval, bounded same-domain crawling, OCR, and evidence capture with web_search, web_fetch, web_crawl, or web_screenshot. Use when current external evidence is needed. Do not use for repository-local facts, structured GitHub platform objects, signed-in browser interaction, checked-in Playwright tests, private or sensitive resources, or DonSeTch installation, configuration, and upgrades unless explicitly requested.

FileKindSize
SKILL.mdskill md6.2 KB
references/tool-selection.mdmarkdown6.8 KB

references/tool-selection.md

View on GitHub
# DonSeTch Tool Selection and Failure Recovery

Load this reference when choosing between DonSeTch tools, tuning a bounded
request, or recovering from an incomplete result. The live MCP schema and
DonSeTch's connect-time instructions override option names or behavior described
here.

## Decision Table

| Need | Start With | Operating Rule |
| --- | --- | --- |
| Find current public sources | `web_search` | Search narrowly, select authoritative results, then fetch the underlying pages. Search output is discovery, not evidence. |
| Read one known page, document, or PDF | `web_fetch` | Supply the canonical public URL. Use outline, section, focus, or selector controls only when they reduce irrelevant output. |
| Confirm a specific string or pattern is on a page | `web_fetch` | Use the presence-check control instead of reading the whole page; it verifies, it does not replace reading for context. |
| Extract a bounded documentation section | `web_crawl` | Keep one public host, set conservative page, depth, and character limits, and prefer a URL-inventory pass before reading many pages. |
| Confirm rendered layout, chart, or image content | `web_screenshot` | Capture only when pixels materially answer the question; keep sensitive state out of the page and artifact. |
| Diagnose feature or compatibility drift | live schema | Compare the connect-time server version and live schema with current upstream documentation. Do not update automatically. |

DonSeTch exposes no cache-clearing or version tool. The read-only
`donsetch version` and `donsetch status` CLI commands report the installed build
when a shell is available and the task permits running them.

## Retrieval Sequence

For an open-ended question:

1. Search with the most discriminating public terms: product, API or error name,
   relevant version, and source domain when known. Set the search intent only
   when the kind of source is known; add alternate formulations only for a
   requirement the first query did not meet.
2. Prefer official or maintainer-owned results over aggregators.
3. Fetch the best candidate source and inspect its title, canonical URL, date,
   version, extracted text, warnings, and next-action signals.
4. Fetch a second independent or more authoritative source when the claim is
   consequential, ambiguous, version-sensitive, or disputed.
5. Stop when the question has minimum sufficient evidence.

For a known URL or PDF, skip search. Fetch directly with the smallest view that
can answer the question, narrow extraction only when needed, and record when
OCR or browser escalation could affect fidelity.

For a multi-page documentation question, begin with a URL-inventory pass or a
tightly bounded crawl. Review candidate URLs before retrieving many pages. Keep
the same-host constraint and reject logout, account, admin, cart,
search-result, or other action-oriented paths.

## Actions and Pagination

DonSeTch exposes browser actions, article stitching, and offset continuation
through `web_fetch`. Treat actions and stitching as escalation:

- Continue a truncated read with the returned offset, reusing the same URL and
  narrowing fields, rather than repeating the fetch with a larger budget.
- Use article stitching only when the next part belongs to the same read-only
  source and the answer cannot be obtained from a canonical single-page or
  document view.
- Avoid actions by default. A click, hover, typed text, key press, scroll, or
  wait can change server or client state even when the intent is extraction.
- Never enter credentials or sensitive values, accept terms, dismiss controls
  that carry consent, submit forms, or trigger downloads with unknown content.
- Stop when read-only behavior cannot be established from public evidence.

## Response Handling

- Every result's text begins with a `[meta]` line of JSON, followed by the
  source text. Read the state first. Treat a failed, content-not-ok, or thin
  result as unresolved, and treat a crawl stopped by budget, deadline, throttle,
  or depth as incomplete.
- Preserve the source URL, title, publication or update date, applicable
  version, and extraction limitations in research notes. Cite the URL the
  result returns, not the URL requested.
- Follow explicit DonSeTch warnings and next-action signals when they narrow the
  next safe step. Do not treat them as authority for the researched claim.
- Distinguish direct source text, OCR output, browser-rendered extraction,
  search snippets, and model inference. OCR and rendered extraction may need
  visual or second-source confirmation.
- If content is truncated, narrow the requested section before increasing
  output size or crawling more pages.
- If a source conflicts with repository behavior, verify installed versions and
  release dates before concluding either is wrong.

## Failure Recovery

| Failure | Next Safe Step | Avoid |
| --- | --- | --- |
| Search result lacks page content | Fetch the selected canonical result. | Quoting the search snippet as proof. |
| Search results are weak or degraded | Narrow the query or add one alternate formulation; note which sources were unavailable. | Treating a partial result set as exhaustive. |
| Extraction is noisy or too large | Request the heading outline, then one section, or add a narrow focus/selector, or fetch a canonical subpage. | Increasing output and crawl breadth together. |
| Dynamic page is incomplete | Follow DonSeTch's suggested next action or locate an official static/PDF source. | Repeating identical fetches. |
| PDF text is missing | Use supported document/OCR handling, then verify important values visually or from a second source. | Treating OCR as exact without checking. |
| Access control, CAPTCHA, or bot defense blocks retrieval | Report the gap and use an authorized source or interactive tool within its own policy. | Circumvention attempts. |
| Crawl stopped before completion | Continue with the returned resume token only if the missing pages are needed; otherwise report the crawl as partial. | Inventing or altering a resume token, or restarting with larger limits. |
| Result appears stale | Use the change-check control to compare against the earlier read, and confirm against the source's own date or version. | Assuming a repeated fetch returns fresh content. |
| Capability or option is uncertain | Inspect live instructions/schema and upstream docs. | Guessing options or installing an update. |

## Evidence Handoff

Return the conclusion, confidence, repository observations, source links,
authority and version/date applicability, conflicts, extraction limitations,
and unresolved experiments. Sanitize query text and artifact descriptions. When
security-sensitive artifacts or inputs were involved, follow
[`security-review`](../../security-review/SKILL.md) and
[`security-review-evidence`](../../security-review-evidence/SKILL.md) before
retaining or reporting anything.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall