rsc-universal 0.1.1

package/skills/reporting/scripts/verify.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — reporting pipeline artifact check. Read-only by default.
+#
+# What it proves about the pipeline this skill emits:
+#   1. A Jinja2 template (*.html.j2 / *.j2 / *.jinja) exists and PARSES (and renders against an
+#      empty sample context without a syntax error).
+#   2. A non-empty report artifact exists (a *.pdf or rendered *.html bigger than a trivial stub).
+#   3. A schedule is defined: a crontab-style line in any file, OR a .github/workflows/*.yml that
+#      contains a `schedule:` block.
+#   4. A delivery step is wired (a script references a send/email/upload/deliver path).
+#   Soft-warn (never fail) if no freshness/failure gate is detected.
+#
+# Targets, in order of precedence:
+#   - explicit paths passed as arguments (files or directories), OR
+#   - the current working directory.
+#
+# It NEVER modifies files and makes NO network/SMTP/API calls — delivery and schedule are validated
+# by structure, not by sending anything.
+#
+# Exit code: 0 on pass OR on a clean/empty target (nothing to check is not a failure).
+# Non-zero ONLY when a found artifact is genuinely broken (template won't parse, only empty artifacts,
+# no schedule definition, or no delivery step) AND the target actually looks like a report pipeline.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+PY="$(command -v python3 || command -v python || true)"
+
+TARGET="${1:-$PWD}"
+if [ ! -e "$TARGET" ]; then
+  err "target does not exist: $TARGET"; exit 1
+fi
+ROOT="$TARGET"; [ -f "$TARGET" ] && ROOT="$(dirname "$TARGET")"
+
+# Collect candidate artifacts.
+TEMPLATES=(); PDFS=(); HTMLS=(); WORKFLOWS=(); SCRIPTS=()
+if [ -d "$TARGET" ]; then
+  while IFS= read -r f; do TEMPLATES+=("$f"); done < <(find "$TARGET" -type f \( -name '*.j2' -o -name '*.jinja' -o -name '*.jinja2' \) 2>/dev/null)
+  while IFS= read -r f; do PDFS+=("$f");      done < <(find "$TARGET" -type f -name '*.pdf'  2>/dev/null)
+  while IFS= read -r f; do HTMLS+=("$f");     done < <(find "$TARGET" -type f -name '*.html' 2>/dev/null)
+  while IFS= read -r f; do WORKFLOWS+=("$f"); done < <(find "$TARGET" -path '*/.github/workflows/*' \( -name '*.yml' -o -name '*.yaml' \) 2>/dev/null)
+  while IFS= read -r f; do SCRIPTS+=("$f");   done < <(find "$TARGET" -type f \( -name '*.py' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' \) 2>/dev/null)
+fi
+
+# If we found nothing that resembles a report pipeline, this is not our target — pass cleanly.
+if [ "${#TEMPLATES[@]}" -eq 0 ] && [ "${#PDFS[@]}" -eq 0 ] && [ "${#HTMLS[@]}" -eq 0 ] \
+   && [ "${#WORKFLOWS[@]}" -eq 0 ] && [ "${#SCRIPTS[@]}" -eq 0 ]; then
+  skip "no report-pipeline artifacts found (template / pdf / html / workflow / script) — nothing to check"
+  exit 0
+fi
+
+fail=0
+
+# 1. Template parses and renders against an empty context.
+if [ "${#TEMPLATES[@]}" -eq 0 ]; then
+  warn "no Jinja2 template (*.j2) found — a report pipeline normally renders from a template"
+elif [ -z "$PY" ] || ! "$PY" -c "import jinja2" >/dev/null 2>&1; then
+  skip "python/jinja2 not available — skipping template render check"
+else
+  for t in ${TEMPLATES[@]+"${TEMPLATES[@]}"}; do
+    if "$PY" - "$t" >/dev/null 2>&1 <<'PYEOF'
+import sys, os
+from jinja2 import Environment, FileSystemLoader
+path = sys.argv[1]
+env = Environment(loader=FileSystemLoader(os.path.dirname(path) or "."), autoescape=True)
+src = open(path, encoding="utf-8").read()
+env.parse(src)  # raises TemplateSyntaxError on a malformed template
+# Render with a permissive (non-strict) empty context: proves it is renderable, not just parseable.
+env.from_string(src).render()
+PYEOF
+    then
+      ok "template parses + renders: $t"
+    else
+      err "template will not parse/render: $t"; fail=1
+    fi
+  done
+fi
+
+# 2. A non-empty artifact exists (PDF > 1KB, or HTML > 200 bytes and containing a tag).
+artifact_ok=0
+for f in ${PDFS[@]+"${PDFS[@]}"}; do
+  size=$(wc -c < "$f" 2>/dev/null || echo 0)
+  if [ "$size" -gt 1024 ]; then ok "non-empty PDF artifact: $f (${size} bytes)"; artifact_ok=1; fi
+done
+for f in ${HTMLS[@]+"${HTMLS[@]}"}; do
+  size=$(wc -c < "$f" 2>/dev/null || echo 0)
+  if [ "$size" -gt 200 ] && grep -q '<' "$f" 2>/dev/null; then
+    ok "non-empty HTML artifact: $f (${size} bytes)"; artifact_ok=1
+  fi
+done
+if [ "$artifact_ok" -eq 0 ]; then
+  if [ "${#PDFS[@]}" -gt 0 ] || [ "${#HTMLS[@]}" -gt 0 ]; then
+    err "found report artifact(s) but all were empty/stub — generation step produced nothing usable"; fail=1
+  else
+    warn "no rendered .pdf/.html artifact yet — run the generation step, then re-verify"
+  fi
+fi
+
+# 3. Schedule definition: a workflow with schedule:, OR a crontab-style line somewhere.
+schedule_ok=0
+for w in ${WORKFLOWS[@]+"${WORKFLOWS[@]}"}; do
+  if grep -Eq '^[[:space:]]*schedule:' "$w" 2>/dev/null; then
+    ok "GitHub Actions schedule defined: $w"; schedule_ok=1
+  fi
+done
+if [ "$schedule_ok" -eq 0 ]; then
+  # crontab-style: 5 fields (or @reboot/@daily etc.) at the start of a line in any file.
+  while IFS= read -r hit; do
+    [ -n "$hit" ] && { ok "cron schedule line found: ${hit}"; schedule_ok=1; break; }
+  done < <(grep -rEl '(^|[[:space:]])(@(reboot|hourly|daily|weekly|monthly|yearly)|([0-9*/,-]+[[:space:]]+){4}[0-9*/,-]+)' \
+            "$ROOT" 2>/dev/null | head -n 1)
+fi
+if [ "$schedule_ok" -eq 0 ]; then
+  err "no schedule definition found (no .github/workflows/*.yml with 'schedule:' and no crontab line) — a report must ship on a cadence"
+  fail=1
+fi
+
+# 4. Delivery step wired: a script references a send/deliver/email/upload path.
+delivery_ok=0
+if [ "${#SCRIPTS[@]}" -gt 0 ]; then
+  if grep -rEliq '(send_?mail|sendmail|\bsend\b|smtp|deliver|email[_-]?connector|upload|drive\.files|messages\.send)' \
+       "${SCRIPTS[@]}" 2>/dev/null; then
+    ok "delivery step wired (send/deliver/upload reference found)"
+    delivery_ok=1
+  fi
+fi
+if [ "$delivery_ok" -eq 0 ]; then
+  err "no delivery step wired — the report renders but nothing ships it (send/email/upload)"
+  fail=1
+fi
+
+# Soft gate: freshness / failure handling (warn only, never fail).
+if [ "${#SCRIPTS[@]}" -gt 0 ] && \
+   grep -rEliq '(fresh|stale|max_age|updated_at|raise|sys\.exit\(1|alert|on_error|try:)' "${SCRIPTS[@]}" 2>/dev/null; then
+  ok "freshness/failure gate detected"
+else
+  warn "no freshness/failure gate detected — add a stale-source check and fail-loud alert before send"
+fi
+
+if [ "$fail" -eq 0 ]; then
+  ok "report pipeline checks passed"
+  exit 0
+fi
+exit 1

package/skills/research-ops/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: research-ops
+description: "Use when someone hands you an open question to find out the truth about — a tech choice, a regulation, a 'what's actually true about X' — and the answer must survive scrutiny: every non-obvious claim dated and sourced, source disagreements surfaced not averaged away, and the deliverable is a cited memo you could defend in a room. Also when refreshing a stale research memo. Triggers: 'research whether A or B is better in 2026 with sources', 'give me a memo I can defend in Monday's meeting', 'settle this argument, is X actually true, cite your sources', 'what's the state of Y with citations', 'investiga a fondo X y cítame las fuentes con fecha', 'fes una recerca a fons amb fonts datades i nivell de confiança'. NOT sizing a market with TAM/SAM/SOM (that is market-research), NOT a standing cadence watch on named rivals (that is competitor-watch)."
+tags: [research-ops, deep-research, source-credibility, citations, verification, synthesis, knowledge-meta]
+recommends: [market-research, competitor-watch, data-scraper, knowledge-ops, decision-records, structured-extraction, technical-writing]
+origin: risco
+---
+
+# Research-ops — the deep-research operating procedure
+
+You are the **method, not the topic**. Someone hands you "go find out about X" and you
+hand back a memo where every load-bearing claim traces to a source, a date, and a
+confidence tier — a document that survives someone reading it adversarially. The topic
+changes every time; the procedure does not.
+
+Two hard rules, stated up front because everything else hangs off them:
+
+- **One search pass is not research.** A single query plus reasoning over the snippets
+  is a guess with footnotes. Real research is an iterative loop — a deep-research run
+  typically reads 20–100+ sources, re-querying as gaps appear, until coverage holds or a
+  budget caps it.
+- **An unsourced claim is not a finding.** If you can't attach a source and a date, it's
+  an assumption — label it as one or cut it. Human review catches AI errors in roughly
+  15–20% of research reports, so structure the output so a reviewer can check each claim,
+  never so they have to trust it.
+
+## The loop
+
+Research is an ordered loop, not a lookup. Run it in this order; each step has a reason.
+
+1. **Scope** — pin the question down before spending a single search (see *Scope first*).
+   Why: a fuzzy question burns the budget on the wrong sources.
+2. **Plan queries** — write 3–6 distinct query angles, not one phrasing repeated. Cover
+   the claim, the counter-claim, and the primary source. Why: you can't triangulate what
+   you only searched one way.
+3. **Fan out** — run the searches in parallel; collect candidate sources. Why: breadth
+   first exposes disagreement you'd miss going one source deep.
+4. **Fetch & read** — open the actual pages, not the result snippets. Read the primary
+   source, not the blog summarizing it. Why: snippets drop caveats, dates, and numbers.
+5. **Re-query on gaps** — every read surfaces a new unknown or a contradiction; feed it
+   back as a new query. Why: this is the part that makes it a loop instead of a list.
+6. **Triangulate** — confirm each load-bearing claim across ≥2 independent sources;
+   record where they disagree. Why: triangulation is the foundation of a credible finding.
+7. **Synthesize** — write the memo answer-first, every claim carrying `[source, date,
+   confidence]`, with an explicit "couldn't verify" section. Why: the memo is the
+   deliverable; the searches were just inputs.
+
+> **Stop rule:** stop when new searches stop changing the answer (coverage plateaus) OR
+> the budget cap is hit — whichever comes first. Looping forever is not rigor.
+
+## Scope first
+
+Refuse to start on an underspecified question. Researching a fuzzy ask produces a fuzzy
+memo and wastes the search budget. Before the first query, get the 2–3 answers that
+change which sources are even relevant.
+
+```text
+Bad  (will waste the budget):  "What car should I buy?"
+Good (scopeable):              "Best used EV under €25k for a 40km daily commute,
+                                bought in Spain in 2026, prioritizing range over trim."
+```
+
+The clarifiers that almost always matter: **constraint** (budget / scale / tolerance),
+**context** (where, for whom, what stack), and **time** ("as of when" — 2026 answers
+differ from 2023 ones). If the asker can't answer them, ask; don't guess and research the
+wrong thing.
+
+## Source credibility
+
+Not every source counts the same. Restrict to **primary / authoritative** sources where
+you can — official docs, standards bodies, regulator pages, company release notes, filings,
+the actual paper. When a claim lives only in secondary commentary, it drops a confidence
+tier. Pick the credibility check by source type:
+
+| Source type | Check to apply | Default confidence |
+|---|---|---|
+| Official docs, standards, regulator, filing, release notes | SIFT — Trace to original; you are already at it | High |
+| Peer-reviewed / scholarly / formal document | CRAAP (Currency, Relevance, Authority, Accuracy, Purpose) | High once it passes |
+| Trade press / reputable news, corroborated by another | SIFT — Find better coverage, confirm elsewhere | Medium |
+| Single blog, vendor marketing, forum post, uncorroborated | SIFT — Investigate the source; treat as a lead, not a fact | Low |
+| AI summary / search snippet | Not a source — open the page it cites | None until traced |
+
+**Lateral reading is the non-negotiable move.** To judge a page, leave it: open a new tab
+and check what others say about the author/org rather than trusting the page's account of
+itself. A site's "About" page is not evidence the site is authoritative. Full SIFT/CRAAP
+walkthrough, lateral-reading recipe, and worked tier examples live in
+[references/credibility-rubric.md](references/credibility-rubric.md).
+
+## Date everything
+
+Every non-obvious claim carries a date, because "true" has a shelf life — a 2024 pricing
+fact or API behaviour may be wrong in 2026. Record **both** dates when they differ:
+
+- **Publication date** — when the source was written/last updated.
+- **Access date** — when you read it (matters for living pages with no clear pub date).
+
+Provenance line grammar (the contract the verify gate checks):
+
+```text
+CLAIM — [Source title](https://url), pub 2026-04-12 / accessed 2026-06-02 · confidence: high
+```
+
+If a source carries no discernible date, that's a finding in itself: record `pub: n/a`,
+keep the access date, and drop it a tier. **Stale → re-verify**: when refreshing an old
+memo, re-run the loop on the dated claims; don't just copy yesterday's citation forward.
+Full skeleton and grammar: [references/memo-template.md](references/memo-template.md).
+
+## Verify load-bearing claims
+
+A claim is **load-bearing** if the answer changes when it's wrong. Triangulate every one
+against **≥2 independent sources** — independent meaning they don't both trace back to the
+same origin (three blogs quoting one press release is one source, not three).
+
+When sources disagree, **surface the disagreement; never average it away.** "Source A says
+X, source B says Y, here's why and which I weight higher" is a finding. Splitting the
+difference into a number neither source supports is a fabrication. If you genuinely find no
+disagreement, say so explicitly — silence reads as "didn't check."
+
+This is why the memo is structured claim → source → date → confidence rather than as
+flowing prose: roughly 15–20% of AI research reports contain an error a human catches on
+review, and they can only catch it if each claim is individually checkable.
+
+## Synthesize
+
+The memo is the deliverable. Structure it so the answer arrives first and the evidence
+backs it up — not a link dump the reader has to assemble themselves.
+
+```markdown
+## Answer
+<the direct answer in 2–4 sentences; the bottom line up front>
+
+## Findings
+- <claim> — [Source](url), pub YYYY-MM-DD / accessed YYYY-MM-DD · confidence: high|med|low
+- <claim, triangulated> — corroborated by [A](url, date) and [B](url, date) · confidence: high
+
+## Disagreements
+- <where sources conflicted, and how you weighted them> — or "none found across N sources"
+
+## Open questions / could not verify
+- <what you could not source; what's still an assumption; what would settle it>
+```
+
+The "Open questions / could not verify" section is mandatory and is not a sign of failure —
+it's the honest boundary of what the evidence supports. A memo with no open questions on a
+hard topic is usually a memo that stopped looking.
+
+## Budget & stop rules
+
+Cap effort so the loop terminates. Sensible defaults for an on-demand run:
+
+- **~5–8 searches** to start; escalate past that only when a real gap or contradiction
+  demands it, not reflexively.
+- **Fetch what you'll cite**, not everything you find — reading 8 sources well beats
+  skimming 40.
+- **Stop** when two more searches don't move the answer (coverage plateau) or the cap is
+  hit. Then write — note in *Open questions* anything the budget left unresolved.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| One search, then reason over the snippets | That's a guess with footnotes, not research | Run the loop: re-query on every gap |
+| Citing the search-result snippet | Snippets drop caveats, dates, numbers | Fetch and cite the actual page |
+| Single-source claim presented as fact | One source can be wrong or biased | Triangulate load-bearing claims across ≥2 independent sources |
+| Averaging two contradicting sources | Invents a number neither source supports | Surface the disagreement and weight it |
+| Trusting a page's self-description | "About us" is not evidence of authority | Lateral-read: check the org elsewhere |
+| Undated citation | A 2023 fact may be false in 2026 | Record pub + accessed date on every claim |
+| No confidence tier | Reader can't tell a filing from a forum post | Tag high/med/low per finding |
+| No "could not verify" section | Hides the boundary of the evidence | Always include open questions |
+| Synthesizing before reading | Conclusion drives the search, not the evidence | Read first, conclude after |
+| Infinite search, no stop rule | Burns budget, never ships the memo | Cap searches; stop at coverage plateau |
+| Topic-creep into market sizing | That's a different skill's job | Route TAM/SAM/SOM to ../market-research |
+| Re-citing a stale memo unchanged | Yesterday's source may be outdated | On refresh, re-verify the dated claims |
+
+## Verify
+
+The memo is a checkable artifact, so there's a gate for it. Run it against the produced
+memo (read-only; it never edits):
+
+```bash
+./scripts/verify.sh --path memo.md     # check one memo
+./scripts/verify.sh --path research/   # scan a directory of memos
+```
+
+It asserts the memo has an answer/summary section, that every finding line carries a
+citation token, that every citation carries a date, that a confidence tier appears, and
+that an "Open questions / unverified" section exists. A missing or empty target is a SKIP,
+not a failure. The gate proves the memo is *sourced and dated* — it does not judge whether
+the answer is correct; that's the capability eval's and your job.
+
+## See also
+
+- [../market-research/SKILL.md](../market-research/SKILL.md) — when the question is "how
+  big is the market / who's in it" (TAM/SAM/SOM), not "what's true about X".
+- [../competitor-watch/SKILL.md](../competitor-watch/SKILL.md) — when you need a standing
+  cadence watch on named rivals, not a one-shot investigation.
+- [../data-scraper/SKILL.md](../data-scraper/SKILL.md) — when the job is bulk-extracting
+  data from many pages; research-ops *uses* fetched pages, it doesn't own scrape infra.
+- [../knowledge-ops/SKILL.md](../knowledge-ops/SKILL.md) — to file what you already know
+  into a durable base; research-ops *produces* findings, knowledge-ops *files* them.

package/skills/research-ops/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — research-ops
+
+These cases are run by the rsc eval harness. `should_trigger` and `should_not_trigger`
+check description routing — does the skill fire on real research asks (including the
+non-obvious "settle this argument" and the Spanish/Catalan phrasings) and stay quiet on
+market-sizing, standing-watch, scraping, and knowledge-filing asks that belong to siblings.
+The `capability` case is a rubric a human or LLM grader scores against an actual research
+run: did the agent loop rather than one-shot, triangulate a load-bearing claim, date and
+tier every claim, surface (or rule out) disagreement, and ship an answer-first memo with an
+open-questions section. There is no automated grading of memo *correctness* — the only
+mechanical check is `scripts/verify.sh`, which lints a produced memo for provenance
+structure (answer section, citations, dates, confidence tiers, open-questions section), not
+for whether the answer is right.

package/skills/research-ops/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: research-ops
+
+should_trigger:
+  - prompt: "Research whether Postgres or ClickHouse is better for our analytics workload in 2026, and give me sources."
+    why: "Open-ended factual investigation needing dated, sourced evidence — the core research-ops job."
+  - prompt: "Give me a memo I can defend in Monday's meeting on the state of EU AI rules right now."
+    why: "Non-obvious phrasing; the deliverable is a defensible, cited memo, which is the research-ops output."
+  - prompt: "Settle this argument for me: is X actually true? Cite your sources."
+    why: "Non-obvious; the verify-and-cite core — find the truth and back it with checkable sources."
+  - prompt: "Investiga a fondo las opciones de almacenamiento y cítame las fuentes con fecha."
+    why: "Spanish; deep research plus dated sources — the loop and the provenance requirement."
+  - prompt: "Fes una recerca a fons sobre això amb fonts datades i nivell de confiança."
+    why: "Catalan; explicitly asks for the full method including dated sources and confidence tiers."
+
+should_not_trigger:
+  - prompt: "How big is the market for AI note-takers? Give me a TAM."
+    route_to: market-research
+    why: "Market-sizing arithmetic (TAM/SAM/SOM), not the general source-evaluated research method."
+  - prompt: "Keep watching Notion's pricing page and tell me when it changes."
+    route_to: competitor-watch
+    why: "Standing cadence watch on a named rival, not a one-shot on-demand investigation."
+  - prompt: "Scrape these 400 product pages into a CSV."
+    route_to: data-scraper
+    why: "Bulk extraction mechanics; research-ops uses fetched pages but does not own scrape infra."
+  - prompt: "Organize my scattered notes into a searchable knowledge base."
+    route_to: knowledge-ops
+    why: "Filing what is already known into a durable base, not producing new sourced findings."
+
+capability:
+  - scenario: "Research whether to adopt library X vs library Y for a 2026 build, and produce a memo."
+    must_include:
+      - "Decomposes the question and runs more than one search pass (iterative loop, not a single query)."
+      - "At least one load-bearing claim triangulated across two or more independent sources."
+      - "Every non-obvious claim carries a source plus a date (publication or accessed) plus a confidence tier."
+      - "Surfaces at least one source-level disagreement, or explicitly states none was found across the sources read."
+      - "Has a separate 'Open questions / could not verify' section."
+      - "Answer-first synthesis with the bottom line up front, not a link dump."
+      - "Stays out of market-sizing (market-research) and standing-watch (competitor-watch) territory."

package/skills/research-ops/references/credibility-rubric.md

@@ -0,0 +1,78 @@
+# Credibility rubric — SIFT, CRAAP, lateral reading, confidence tiers
+
+The body picks the check by source type. This is the full walkthrough you offload to when
+a source is borderline.
+
+## SIFT — for web and popular sources
+
+Mike Caulfield's SIFT is fast and built for the open web, where the question is usually
+"can I trust this at all" rather than "is this scholarship sound."
+
+- **Stop.** Before you read or quote, pause. Do you recognize the source? Is your reaction
+  ("this confirms what I wanted") doing the evaluating for you? Stop again whenever you
+  feel certainty arriving too easily.
+- **Investigate the source.** Who published this, and what's their stake? A vendor blog
+  arguing its own product wins is a lead, not a neutral finding. You're not reading the
+  article yet — you're sizing up who wrote it.
+- **Find better coverage.** Don't fixate on the page you landed on. Is there a more
+  authoritative source making the same claim? If the only place a claim appears is one
+  blog, that's a low-confidence claim by definition.
+- **Trace to the original.** Most web claims are re-reports. Follow the chain back to the
+  primary source — the actual filing, paper, release note, dataset. Quote that, with its
+  date, not the re-report.
+
+## CRAAP — for scholarly and formal-document sources
+
+When the source is a paper, standard, regulation, or formal report, evaluate it on its
+merits:
+
+- **Currency** — when was it published or last revised? Is that recent enough for the
+  claim? (A 2021 benchmark is stale for a 2026 performance claim.)
+- **Relevance** — does it actually address your question, or just mention the keyword?
+- **Authority** — who are the authors/issuer, and are they credentialed for this?
+- **Accuracy** — is it evidenced, cited, reproducible? Does it agree with other sources?
+- **Purpose** — inform, sell, persuade, or advocate? Purpose colours which facts get
+  emphasized and which get omitted.
+
+## Lateral reading — the move that does the work
+
+Vertical reading (staying on the page, reading top to bottom, judging it by how
+professional it looks) is how people get fooled. **Lateral reading** is leaving the page
+to judge it:
+
+1. Open a new tab.
+2. Search the author's or organization's name plus "funding", "owned by", "criticism",
+   or the claim itself.
+3. Read what *independent* parties say about them before you trust what they say about
+   themselves.
+
+A polished site, a confident tone, and an "About us" page are presentation, not evidence.
+The org's reputation as reported by others is the evidence.
+
+## Confidence tiers, with worked examples
+
+Assign a tier to every load-bearing claim. Use it in the provenance line.
+
+| Tier | When | Worked example |
+|---|---|---|
+| **High** | Primary/authoritative source, or a claim corroborated across ≥2 independent ones | A regulator's own published rule text, accessed at the source; or two independent reputable outlets reporting the same dated figure |
+| **Medium** | Reputable secondary source, single, plausible but not yet corroborated | A respected trade-press article reporting a number with a date, no second source found yet |
+| **Low** | Single blog/forum/vendor claim, uncorroborated, or no discernible date | One personal blog asserting a benchmark with no methodology and no other source repeating it |
+
+Worked walkthrough:
+
+- **Government filing → High.** You're at the primary source; SIFT's "trace to original"
+  is already satisfied. Cite it with its publication date.
+- **Corroborated trade press → Medium → can rise to High.** One outlet reports a figure;
+  you find a second, independent outlet (not republishing the first) with the same figure
+  and date. Independence is what promotes it; two outlets quoting one wire story stay
+  Medium.
+- **Single blog → Low.** Useful as a lead — it might point you to a primary source worth
+  tracing — but never cite it as the basis for a load-bearing claim. If it's the only
+  thing you can find, the claim itself is low-confidence; say so in the memo.
+
+## Independence test
+
+Two sources are independent only if they don't both derive from the same origin. Three
+articles quoting the same press release are **one** source. Before you call a claim
+triangulated, ask: would these still agree if the one upstream source were wrong?

package/skills/research-ops/references/memo-template.md

@@ -0,0 +1,63 @@
+# Memo template — skeleton + provenance grammar
+
+This is the contract `scripts/verify.sh` checks against. Keep the section headings and the
+provenance line shape, and the gate passes.
+
+## Provenance line grammar
+
+Every finding line carries one of these shapes:
+
+```text
+<CLAIM> — [Source title](https://url), pub 2026-04-12 / accessed 2026-06-02 · confidence: high
+<CLAIM> — corroborated by [A](https://a, 2026-03-01) and [B](https://b, 2026-05-10) · confidence: high
+<CLAIM> — [Source](https://url), pub n/a / accessed 2026-06-02 · confidence: low
+```
+
+Rules:
+
+- A **citation token** is required on every finding: a Markdown link or an explicit URL.
+- A **date** is required: `pub YYYY-MM-DD`, `accessed YYYY-MM-DD`, or both. If the source
+  has no publication date, write `pub n/a` and keep the access date — don't drop the date
+  field entirely.
+- A **confidence tier** token is required: `high`, `med`/`medium`, or `low`.
+- Triangulated claims name ≥2 independent sources, each with its own date.
+
+## Memo skeleton
+
+```markdown
+# Research memo — <question, scoped>
+
+_As of: 2026-06-02 · researcher: <name/agent> · budget: <N searches, M sources read>_
+
+## Answer
+<The direct answer, 2–4 sentences. Bottom line up front. If the honest answer is
+"it depends", state on what.>
+
+## Findings
+- <claim> — [Source title](https://url), pub 2026-04-12 / accessed 2026-06-02 · confidence: high
+- <claim, triangulated> — corroborated by [A](https://a, 2026-03-01) and [B](https://b, 2026-05-10) · confidence: high
+- <weaker claim> — [Blog](https://url), pub n/a / accessed 2026-06-02 · confidence: low
+
+## Disagreements
+- <where sources conflicted; what each said; which you weight higher and why>
+- (If none: "No source-level disagreement found across the N sources read.")
+
+## Open questions / could not verify
+- <what you could not source>
+- <what remains an assumption, flagged as such>
+- <what would settle it if someone spent more budget>
+
+## Sources
+1. [Source title](https://url) — pub 2026-04-12, accessed 2026-06-02 — <one-line what it is / why trusted>
+2. ...
+```
+
+## What "good" looks like
+
+- The **Answer** stands alone — a reader who stops there still got the bottom line.
+- Every **Findings** line is independently checkable: click the link, see the date, see
+  the tier.
+- **Disagreements** is never empty silently — either it lists conflicts or it states none
+  were found.
+- **Open questions** is present even on a confident memo; it's the boundary of the
+  evidence, not an admission of failure.