Skip to content

web-research

General web research for OKF matters — legislation, statutory instruments, regulations, standards (BS/EN), guidance, news and web sources — with token-efficient layered fetching, source hierarchy, and mandatory citation discipline (URL + access date + verbatim quote). Use when the user asks to research, look up, find or verify anything on the web outside case law (use scotcourts/ssdt for those) — e.g. "what does the Building Safety Act 2022 say about X", "find the current version of section 12 of the Housing Grants Act", "what changed in the latest JCT amendment". Adapted from the community 'efficient-web-research' protocol (sickn33/agentic-awesome-skills, MIT); legal citation layer per OKF case-law standards.

Source: .opencode/skills/web-research/SKILL.md — site rebuilt 2026-09-05.

Web Research

Core principle

Fetch the minimum needed to answer. Skim before you dive. Stop when you can answer.

Every unnecessary fetch wastes tokens and adds noise. Escalate fetch depth only when shallower layers fail.

Tooling in this environment (opencode on Windows)

  • webfetch (URL → markdown/text) — first choice for most pages, strips HTML automatically.
  • PowerShell via bash for APIs and machine-readable sources: Invoke-WebRequest / Invoke-RestMethod (e.g. api.github.com, legislation.gov.uk JSON endpoints). Always send -Headers @{"User-Agent"="okf"} to API hosts.
  • webapp-testing skill — only for JS-rendered or auth-gated pages where plain fetching returns empty/placeholder content. It is the last resort; never use it for static pages.
  • scotcourts / ssdt / case-law skills — any question about judgments or tribunal findings belongs to those skills, not this one. This skill covers everything else: statutes, SIs, regs, standards, guidance, articles, news.

Step 1 — Classify the input

Input Type Example Go To
Specific page URL legislation.gov.uk/ukpga/2022/30/section/3 URL Protocol
Topic / query (no URL) "retention money adjudication what changed" Search Protocol
Multiple URLs List of links to compare Multi-URL Protocol
PDF / file link .pdf, .txt, .md, .csv URL File Protocol
GitHub URL repo / file / issue GitHub Protocol
Judgment / tribunal any case law question hand off to scotcourts / ssdt → case-law

Search Protocol

Step 1 — Sharpen the query before searching

Do NOT search the raw user query. Transform it first:

  • Add specificity: act name + section number, regulation name, "current version", "as amended"
  • Add jurisdiction terms: "UK" / "Scotland" / "England and Wales" where it matters (construction law is heavily devolved; wrong jurisdiction = wrong answer)
  • Add recency when relevant (e.g. "2025", "June 2026")
  • Remove filler: "how do I", "what is the", "can you explain"

Step 2 — Search and select

  1. Run the search; scan titles + snippets ONLY — do not fetch yet.
  2. Pick the TOP 1-2 results (max 3 in complex cases).
  3. Source hierarchy — prefer, in order: legislation.gov.uk (primary + SI text), gov.uk / gov.scot (official guidance), official bodies (HSE, LABC, RICS, RIBA, JCT), the originating organisation's site (e.g. an adjudicator's own site for its decisions), established legal publishers (Lexis/Westlaw summaries only as leads — never cite them as the source of statutory text), authoritative news (Law Society Gazette, Construction News). Skip aggregator blogs, paywalled sites, AI-generated content farms, forums.
  4. For any claim the user will rely on: prefer the primary source over summaries of it. A secondary article stating what an Act says is a lead, never a citation.

Step 3 — Fetch selected results

Apply the URL Protocol to each selected URL. Process one at a time — only fetch the second URL if the first didn't answer the question.

Token rules: never read more than 3 URLs per query; if the snippet already answers a simple factual question, use the snippet; never dump raw HTML into context.

URL Protocol

Layered fetch

Layer 1 — Skim:  fetch, read headings + first paragraph only.
                 Answerable? YES → STOP. NO → continue.
Layer 2 — Targeted extract: fetch with anchor (#section), extract the relevant section only.
Layer 3 — Full fetch: strip nav/footers/cookie banners/ads; cap at ~2000 tokens; summarise before answering.
Layer 4 — Browser (last resort): webapp-testing skill only when the page is JS-rendered
                 or auth-gated and layers 1-3 return empty/garbled content.

legislation.gov.uk specifics (critical for statutory research)

  • Point-in-time is the default. A section's "current version" differs from its "original version". If the user asks "what does s.12 say now", fetch the current version; if they ask what the contract incorporated, note the date the contract was made and fetch the version in force at that date.
  • Use the API when useful: https://www.legislation.gov.uk/{legislation}/data.xml (or ?view=... variants) returns structured text; otherwise fetch the HTML page and strip.
  • Quote verbatim, never paraphrase the statutory text. Copy the words exactly; put them in quotation marks with the source.
  • Note the version header shown on the page (e.g. "UK Public General Acts · 2022 c. 30 · Section 3 — current").
  • SIs: include the SI number and year (e.g. "SI 2023/1385") — the number is part of the citation.

What to strip from fetched pages

Remove: navigation menus, cookie banners, "related articles", footers, share buttons, ads, sponsored content. Keep: the article/documentation body, tables with data, numbered steps.

Multi-URL Protocol

  1. Skim all URLs first (Layer 1 each).
  2. Group by relevance to the question.
  3. Deep-fetch only the most relevant 1-3.
  4. Summarise each in 3-5 sentences before combining; never dump raw content from multiple pages.

File Protocol

  • .md / .txt / .csv — read directly.
  • .pdf — extract text (pdf skill or okf-ocr conventions); do not paste binary content into context.
  • .json / .yaml — parse structure, summarise schema + key values.
  • Large files (>500 lines) — read first 100 + last 20 lines, search for relevant sections only.

GitHub Protocol

  • Always prefer the GitHub API over scraping: https://api.github.com/repos/{owner}/{repo} (metadata), .../readme (README), .../contents/{path} (base64 file content), .../git/trees/{ref}?recursive=1 (file tree).
  • README answers ~70% of "what does this repo do" questions — try it first. Never fetch more than 3 files per research turn. Decode base64 before passing to context.

Anti-patterns (never)

Anti-pattern Do this instead
Fetching a full page for a simple fact Use the snippet or targeted anchor
Browser automation for static pages Plain fetch first
Searching with the raw user query Sharpen it
Fetching 5+ search results Max 3, stop when answered
Dumping raw HTML into context Strip to the relevant text
Citing a secondary article for what a statute says Fetch legislation.gov.uk and quote it
Re-fetching the same URL Cache in context, reuse
Citing a page you never opened A title from search results is a LEAD, never a citation

Mandatory citation discipline (OKF)

Every factual proposition you return from research carries a citation record:

Source: <full URL>
Accessed: <date>  (today's date)
Quote:   <verbatim passage in quotation marks — exact words only>
  • Never paraphrase a quote and present it as the words of the source. No quote = no verbatim claim.
  • If a fact cannot be verified against an opened source, mark it [UNVERIFIED] and say so — the fact-checker gate treats unmarked unverified facts as errors.
  • If the source is paywalled or the content cannot be confirmed, say "could not verify — paywalled/blocked" rather than guessing.
  • When the research feeds a court document or submission, the proposition-level citations must survive into the draft: the draft-augmenter / submission-planner skills expect exactly these Source/Accessed/Quote records.

Output format

Source: [URL or "Web search for: <query>"]
Summary: [2-5 sentences]
Answer: [direct answer]
Confidence: [High / Medium / Low — based on source quality]

For multiple sources: 

Source 1: ...
Source 2: ...
Combined Answer: ...

Never output raw HTML fragments, full page dumps, or unattributed information.

Self-learning

Append lessons (wrong sources, API quirks, legislation.gov.uk version traps, jurisdiction traps) to learnings.md in this skill's folder.