@damiangilgonzalez/harness 1.3.7

package/skills/reporting/references/pipeline.md

@@ -0,0 +1,213 @@
+# reporting — full worked pipeline
+
+The four layers end to end: **fetch → narrate → render → deliver**, plus schedule and reliability
+gate. Pinned stack as of 2026-06-02: `pandas`, `Jinja2`, `WeasyPrint==68.1`, `Matplotlib`. Re-check
+PyPI and pin what you resolve.
+
+```text
+report/
+  templates/report.html.j2     # one template, scoped by params
+  metrics.csv                  # the agreed source (owned by the data team)
+  render.py                    # fetch → narrate → render
+  deliver.py                   # render → deliver (calls email-connector / google-workspace)
+  recipients.yaml              # per-recipient params, NOT forked templates
+  requirements.txt             # pandas, jinja2, weasyprint==68.1, matplotlib, pyyaml
+  .github/workflows/report.yml # the schedule (zero-infra option)
+```
+
+## 1. The Jinja2 template skeleton
+
+```html
+<!-- templates/report.html.j2 -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<style>
+  @page { size: A4; margin: 18mm; }
+  body { font: 11pt/1.45 "Helvetica Neue", Arial, sans-serif; color: #1a1a1a; }
+  h1 { font-size: 20pt; margin: 0 0 2mm; }
+  .summary { background: #f4f6f8; border-left: 4px solid #2563eb; padding: 4mm 5mm; }
+  table { width: 100%; border-collapse: collapse; margin-top: 6mm; font-size: 10pt; }
+  th, td { text-align: left; padding: 2mm 3mm; border-bottom: 1px solid #e2e8f0; }
+  .delta-up { color: #15803d; } .delta-down { color: #b91c1c; }
+</style>
+</head>
+<body>
+  <h1>{{ title }}</h1>
+  <p><strong>Period:</strong> {{ period }}</p>
+
+  <section class="summary">
+    <h2>Executive summary</h2>
+    <p>{{ summary }}</p>
+    <ul>{% for t in takeaways %}<li>{{ t }}</li>{% endfor %}</ul>
+  </section>
+
+  {% if chart_b64 %}<img src="data:image/png;base64,{{ chart_b64 }}" style="width:100%">{% endif %}
+
+  <table>
+    <thead><tr><th>Week</th><th>Revenue</th><th>WoW</th></tr></thead>
+    <tbody>
+      {% for r in rows %}
+      <tr>
+        <td>{{ r.week }}</td><td>€{{ "{:,.0f}".format(r.revenue) }}</td>
+        <td class="{{ 'delta-up' if r.wow >= 0 else 'delta-down' }}">{{ "%+.1f"|format(r.wow) }}%</td>
+      </tr>
+      {% endfor %}
+    </tbody>
+  </table>
+</body>
+</html>
+```
+
+## 2. Render: fetch → narrate → render (WeasyPrint pinned)
+
+```python
+# render.py
+import base64, io
+import pandas as pd
+import matplotlib
+matplotlib.use("Agg")                      # headless: no display needed in CI
+import matplotlib.pyplot as plt
+from jinja2 import Environment, FileSystemLoader
+from weasyprint import HTML                 # WeasyPrint==68.1
+
+def chart_png_b64(df: pd.DataFrame) -> str:
+    fig, ax = plt.subplots(figsize=(8, 2.6))
+    ax.plot(df["week"], df["revenue"], marker="o")
+    ax.set_title("Revenue by week"); ax.grid(True, alpha=0.3)
+    peak = df["revenue"].idxmax()           # annotate the anomaly, don't ship a bare chart
+    ax.annotate("peak", (df["week"][peak], df["revenue"][peak]),
+                textcoords="offset points", xytext=(0, 8))
+    buf = io.BytesIO(); fig.savefig(buf, format="png", bbox_inches="tight", dpi=130)
+    plt.close(fig)
+    return base64.b64encode(buf.getvalue()).decode()
+
+def narrate(cur: float, prev: float) -> tuple[str, list[str]]:
+    delta = (cur - prev) / prev * 100
+    flag = " — investigate" if abs(delta) >= 20 else ""
+    summary = (f"Revenue {'up' if delta >= 0 else 'down'} {abs(delta):.1f}% WoW "
+               f"(€{cur:,.0f} from €{prev:,.0f}){flag}.")
+    takeaways = [summary, "Pipeline coverage holding at 3.1x.", "No SLA breaches this period."]
+    return summary, takeaways
+
+def build_pdf(df: pd.DataFrame, params: dict) -> bytes:
+    df = df[df["region"] == params["region"]].reset_index(drop=True)
+    df["wow"] = df["revenue"].pct_change() * 100
+    cur, prev = df["revenue"].iloc[-1], df["revenue"].iloc[-2]
+    summary, takeaways = narrate(cur, prev)
+    env = Environment(loader=FileSystemLoader("templates"), autoescape=True)
+    html = env.get_template("report.html.j2").render(
+        title=f'{params["region"]} weekly revenue', period=params["period"],
+        summary=summary, takeaways=takeaways, chart_b64=chart_png_b64(df),
+        rows=df.tail(8).to_dict("records"),
+    )
+    return HTML(string=html).write_pdf()     # 68.1: stable A4/@page CSS
+```
+
+## 3. Per-recipient parameterization (one template, many scopes)
+
+```yaml
+# recipients.yaml — same template, audience-scoped params
+- email: emea-lead@acme.com
+  region: EMEA
+  period: "2026-W22"
+- email: amer-lead@acme.com
+  region: AMER
+  period: "2026-W22"
+```
+
+```python
+# deliver.py — render once per recipient, hand the bytes to email-connector
+import yaml, pandas as pd
+from render import build_pdf
+# from email_connector import send  # transport is email-connector's job, not this skill's
+
+def main():
+    df = pd.read_csv("metrics.csv", parse_dates=["updated_at"])
+    freshness_gate(df, period="2026-W22")            # see §5 — refuse stale before any send
+    for r in yaml.safe_load(open("recipients.yaml")):
+        pdf = build_pdf(df, r)
+        assert pdf and len(pdf) > 1024, "empty PDF — refusing to send"
+        # send(to=r["email"], subject=f'Weekly revenue — {r["region"]}',
+        #      body="Your weekly report is attached.", attachments=[("report.pdf", pdf)])
+
+if __name__ == "__main__":
+    main()
+```
+
+## 4. Schedule
+
+**cron** (you already run a host):
+
+```cron
+# /etc/cron.d/weekly-revenue — Mondays 08:00, log everything, owner gets stderr by mail
+0 8 * * 1 reportbot cd /opt/report && python deliver.py >> /var/log/report.log 2>&1
+```
+
+**GitHub Actions** (zero infra — the recommended cloud option):
+
+```yaml
+# .github/workflows/report.yml
+name: weekly-revenue-report
+on:
+  schedule:
+    - cron: "0 6 * * 1"        # 06:00 UTC ≈ 08:00 Europe/Madrid; cron here is always UTC
+  workflow_dispatch: {}        # manual re-run for testing
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install -r requirements.txt   # weasyprint==68.1 pinned here
+      - run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangoft2-1.0-0
+      - run: python deliver.py
+        env:
+          SMTP_TOKEN: ${{ secrets.SMTP_TOKEN }}   # transport secret, owned by email-connector
+```
+
+Note: GitHub Actions `schedule:` cron is **UTC only** and may lag a few minutes under load — never
+schedule a report to the exact minute it is "due"; give it slack.
+
+## 5. Reliability gate
+
+```python
+# freshness + fail-loud. A report that ships stale numbers is worse than one that doesn't ship.
+from datetime import datetime, timedelta, timezone
+
+def freshness_gate(df, period: str, max_age_hours: int = 26):
+    latest = df["updated_at"].max()
+    if latest.tzinfo is None:
+        latest = latest.tz_localize("UTC")
+    age = datetime.now(timezone.utc) - latest.to_pydatetime()
+    if age > timedelta(hours=max_age_hours):
+        raise RuntimeError(
+            f"STALE SOURCE: newest row is {age} old (> {max_age_hours}h) for {period}. "
+            f"Refusing to send. Page the source owner — do NOT clean the data here (data-cleaning)."
+        )
+```
+
+```python
+# Wrap the whole run so a failure pages the owner instead of failing silently.
+import sys, traceback
+def run_guarded(fn, owner_alert):
+    try:
+        fn()
+    except Exception as exc:           # noqa: BLE001 — we want everything
+        owner_alert(f"REPORT FAILED: {exc}\n{traceback.format_exc()}")
+        sys.exit(1)                    # non-zero so the scheduler also flags it
+```
+
+**Dead-report cleanup:** if delivery telemetry shows the last N editions went unopened, stop the
+schedule and notify the owner. An unread recurring report is pure cost and inbox noise — killing it is
+part of owning the report, not a failure.
+
+## Boundary reminders
+
+- The **transport** (SMTP/Gmail/Drive upload) is [`email-connector`](../../email-connector/SKILL.md)
+  / [`google-workspace`](../../google-workspace/SKILL.md) — this pipeline calls it, never reimplements it.
+- **Spreadsheet output** for analysts → [`spreadsheet-ops`](../../spreadsheet-ops/SKILL.md).
+- **Notion / living-doc destination** → [`notion-connector`](../../notion-connector/SKILL.md).
+- **Generic multi-step job wiring** beyond the report → [`automation-flows`](../../automation-flows/SKILL.md).

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/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: research
+description: "Researches a question against high-confidence primary sources and captures the findings as a Markdown file in the repo. Use when the person wants to research a topic, gather facts from documentation or an API, or delegate the reading work to a background agent."
+tags: ["research", "documentation", "background-agent"]
+profiles: [core, ui, full]
+---
+
+Levanta un **agente en segundo plano** para hacer la investigación, así sigues trabajando mientras él lee.
+
+Su trabajo:
+
+1. Investigar la pregunta contra **fuentes primarias** — documentación oficial, código fuente, especificaciones, APIs de primera parte — no un resumen secundario de ellas. Sigue cada afirmación hasta la fuente que la posee.
+2. Escribir los hallazgos en un único fichero Markdown, citando la fuente de cada afirmación.
+3. Guardarlo donde el repo ya guarde ese tipo de notas; imita la convención existente, y si no hay ninguna, ponlo en un sitio sensato y di dónde.

package/skills/research/evals/cases.yaml

@@ -0,0 +1,32 @@
+skill: research
+
+should_trigger:
+  - prompt: "Investiga como funciona esta API de terceros antes de integrarla."
+    why: "Disparador directo de research."
+  - prompt: "Necesito que alguien lea la documentacion oficial y me resuma los hechos."
+    why: "Disparador directo de research."
+  - prompt: "Delega esta investigacion a un agente en segundo plano."
+    why: "Disparador directo de research."
+  - prompt: "Research this topic against primary sources and write up the findings."
+    why: "Disparador directo de research."
+  - prompt: "Reune hechos verificados sobre esta libreria antes de decidir."
+    why: "Disparador directo de research."
+
+should_not_trigger:
+  - prompt: "Implementa la funcion que ya investigamos."
+    route_to: "implement"
+    why: "Implementar la funcion investigada es el trabajo de implement, no de research."
+  - prompt: "Escribe un ticket con lo que se va a hacer."
+    route_to: "to-tickets"
+    why: "Escribir un ticket es el trabajo de to-tickets, no de research."
+  - prompt: "Revisa el codigo que hemos escrito hoy."
+    route_to: "revision-de-cambios"
+    why: "Revisar el trabajo sin commitear de hoy es el trabajo de revision-de-cambios, no de research."
+  - prompt: "Genera un prototipo de la pantalla."
+    route_to: "prototype"
+    why: "Generar un prototipo desechable es el trabajo de prototype, no de research."
+
+capability:
+  - scenario: "El usuario quiere investigar un tema contra fuentes primarias."
+    must_include:
+      - "fuente"

package/skills/research-ops/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: research-ops
+description: "Use when someone hands you an open question whose answer must survive scrutiny — a tech choice, a regulation, a what-is-actually-true-about-X — with every non-obvious claim dated and sourced, source disagreements surfaced rather than averaged away, and a cited memo as the deliverable. Also for refreshing a stale research memo. 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, write-adr, 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."