@iowarp/clio-coder 0.3.1 → 0.3.3

package/skills/planning/product-intent/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: product-intent
+description: Use at the start of a greenfield product effort, when the user wants a problem-first product document — "why are we building this", "write the product thesis", "PRD for this idea". Interviews for the problem, evidence, and a falsifiable hypothesis; writes an intent-only PRD with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - write
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/product-intent
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/product-intent
+  eval-status: smoke-checked
+  model-size: large
+  agents:
+    - main
+---
+
+# Product Intent
+
+A PRD is intent: the problem and the hypothesis about solving it, in a form a
+team can challenge before building and judge after shipping. Engineering
+decisions (library, data model, boundaries) never enter it; they belong to
+`architecture`.
+
+Two hard guards, checked before writing anything:
+
+1. **Intent-framed.** If only one solution could fit your problem statement,
+   you wrote a spec, not a PRD. "Give users a way to group related replies"
+   passes; "add a reply button" fails.
+2. **Never invent requirements.** Anything unknown ships as
+   "TBD — needs validation", verbatim, never as a plausible guess.
+
+## Step 0 — Ground in evidence
+
+If the user passed reference docs (interviews, support tickets, analytics,
+competitor notes), read them first and treat them as evidence. If none were
+passed, ask whether any exist before interviewing.
+
+## The interview
+
+Ask in clusters via `ask_user`, and GATE: post the cluster, stop, wait for
+answers. Never answer your own questions, never roll into the next phase in
+the same turn. Thin answers get reflected back and dug into.
+
+If the user declines the interview ("just write it"): honor it, name what
+you will have to leave TBD, ask only the two or three highest-leverage
+questions, and mark everything else "TBD — needs validation".
+
+1. **Initiate.** Input given → restate and confirm. Blank → "What do you
+   want to build? A few sentences." GATE.
+2. **Foundation.** Who has the problem (a specific role, not "users")? What
+   is the observable pain? How do they cope today (workaround, competitor,
+   tolerating)? Why now? And the switch test: do you solve it so much better
+   they leave their current cope? No switch case → no product yet; say so.
+   GATE.
+3. **Users.** One-sentence vision · primary user (role, context, trigger) ·
+   job-to-be-done ("When [situation], I want [motivation], so I can
+   [outcome]") · explicit non-users · constraints. GATE.
+4. **Hypothesis.** Co-write the falsifiable bet. The WRONG condition is the
+   most-skipped line and the one that makes it a hypothesis:
+
+   ```
+   We believe [change] will cause [users] to [do Y], resulting in [outcome].
+   RIGHT if [leading signal] within [timeframe].
+   WRONG if [counter-signal / a guardrail moves].
+   ```
+
+   No hypothesis ships without a WRONG condition. GATE.
+5. **MVP and doors.** MVP = the thinnest end-to-end line that proves the
+   hypothesis right or wrong, not "the product, smaller". Mark each major
+   call two-way door (reversible → just build) or one-way door (expensive to
+   undo → flag for a spike in architecture). GATE before generating.
+
+Optional pressure test when useful: value (do they want it more than their
+cope?), usability, feasibility, viability. Most ideas over-argue feasibility
+and under-argue value.
+
+## Generate
+
+Write to `docs/<kebab-slug>.prd.md` (slug from the core idea; repo root if
+no `docs/`; a user-supplied path always wins). Never hardcode `PRD.md` — a
+second PRD must not overwrite the first. Sections, scannable, product only:
+
+1. **Problem statement** — who, what pain, cost of not solving it.
+2. **Evidence** — quote/data/observation, or "Assumption — validate via
+   [method]".
+3. **Thesis** — why this, why now, why it beats the current cope.
+4. **Hypothesis** — the RIGHT/WRONG block, verbatim.
+5. **Target user & JTBD** — plus non-users.
+6. **MVP** — the thinnest proving line.
+7. **Success metrics** — outcome-shaped: metric · target · how measured.
+   "Engagement" is not a metric.
+8. **Non-goals.**
+9. **Open questions** — named checkboxes, never hidden.
+
+## Done when
+
+The file exists; the summary to the user leads with thesis and hypothesis,
+counts evidenced-vs-assumed claims and open questions; and the next step is
+offered: `architecture` for the engineering decisions this PRD
+deliberately left open. Failing any of the five tests below means not done:
+evidence-grounded problem · hypothesis with separate RIGHT and WRONG ·
+outcome-shaped metrics · explicit non-goals · zero engineering decisions.

package/skills/planning/product-intent/evals.md

@@ -0,0 +1,36 @@
+# Evals — product-intent
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — greenfield idea
+Prompt: "I want to build a log-triage tool for HPC operators, write the PRD."
+Expected:
+- Interviews in gated clusters; never answers its own questions.
+- Hypothesis block has both RIGHT and WRONG conditions.
+- Output lands at `docs/<slug>.prd.md`, not `PRD.md`.
+- Zero engineering decisions (no stack, no schema, no libraries).
+- Unknowns say "TBD — needs validation", not invented requirements.
+
+## S2 — user declines the interview
+Prompt: "skip the questions, just write it."
+Expected:
+- Asks only 2-3 highest-leverage questions, names what goes TBD.
+- No fabricated evidence or metrics.
+
+## S3 — solution-shaped request
+Prompt: "PRD for adding a reply button."
+Expected:
+- Reframes to the underlying problem; the problem statement admits more
+  than one solution.
+
+## Baseline failure modes to watch for (RED)
+- One-shot PRD generated from thin air.
+- Hypothesis with no WRONG condition.
+- "React + Postgres" appearing anywhere in the document.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Interview degraded gracefully headless; PRD written to docs/, judge 5/5.

package/skills/planning/tech-spec/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: tech-spec
+description: Write a typed call-stack architecture handoff — code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only.
+version: 0.1.0
+license: Apache-2.0
+disable-model-invocation: true
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - code_nav
+  - write
+  - ask_user
+requires:
+  - skill:tdd
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/tech-spec
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/dmmulroy/skills/tree/main/tech-spec
+  eval-status: smoke-checked
+  model-size: large
+  provisional: true
+  agents:
+    - main
+---
+
+# Tech Spec
+
+A tech spec is a typed call-stack architecture handoff: contracts as
+TypeScript pseudocode plus end-to-end execution flows. Prose explains why;
+types and call stacks define what changes. Design only — never implement,
+and save a file only when the user asks; otherwise return the spec inline.
+
+## Choose the path
+
+- **Path A — convert context to spec**: the conversation, docs, or codebase
+  already describe the change.
+- **Path B — interview first**: not enough problem, constraints, or
+  acceptance criteria exist. Say so, then interview one question at a time
+  with a recommended answer per question (the grill-me posture); anything
+  answerable by exploring the codebase is explored, not asked. When context
+  suffices, run Path A. Never invent requirements to skip the interview.
+
+## Path A
+
+1. **Load local context.** Inspect existing code and docs for vocabulary,
+   module layout, error style, adapters, test conventions. Done when the
+   spec introduces no pattern, library, or schema style without checking
+   local precedent.
+2. **Extract the design problem.** Current state, problem, callers, goals,
+   non-goals, constraints, invariants, affected systems, entrypoints,
+   risks. Unknowns become open questions, never plausible filler. Done when
+   every claimed constraint traces to conversation, code, docs, or an open
+   question.
+3. **Explore alternatives.** 2-3 designs differing materially — interface
+   shape, seam placement, ownership, call stack, module boundaries — not
+   just names. Sketch each: domain types, interfaces, failure types, seams,
+   entrypoint-to-effect call stack, test strategy, trade-offs. Compare on
+   caller burden, module depth, locality of change, seam placement,
+   testability through real seams, complexity. Done when the
+   recommendation is chosen after the comparison, not before.
+4. **Specify the contracts.** For the recommended design, every new,
+   changed, or deleted type, signature, interface, error union, adapter,
+   DTO, and API gets a concrete sketch — or an explicit reason no new
+   contract is needed. Name what each layer may know and what must not
+   leak across each seam.
+5. **Specify call stacks.** Every affected behavior gets an entrypoint →
+   side-effect → response trace with the type/data flow (`raw input →
+   parser → domain input → service → adapter → typed result → projection →
+   output`), current-vs-proposed when changing behavior, and failure /
+   retry / idempotency flow where reachable.
+6. **Map files.** Files to add, change, delete; test files; config or
+   migration files. Each maps to the contract or call-stack step it owns.
+7. **Write the TDD plan.** Vertical red-green slices per the `tdd` skill:
+   one failing behavior test, minimal implementation, repeat. Cover happy
+   paths, failure paths, parser rejection, invariants, changed seams — or
+   state why a path is deliberately untested.
+
+## Spec outline
+
+Use this shape (omit sections that truly do not apply, but never omit
+contracts, seams, call stacks, or the test plan for being hard):
+
+```md
+# <Title>
+## Summary · Context / Current State · Goals · Non-Goals · Invariants ·
+## Design Constraints
+## Alternatives Considered (Option 1..3)
+## Recommendation · Proposed Design
+## Domain Model and Types · Types, Interfaces, and APIs
+## Seams, Boundaries, Adapters, and Implementations
+## Call Stacks and Data Flow (current / proposed / failure / retry)
+## Files to Add / Change / Delete
+## TDD Test Plan
+## Risks and Open Questions
+```
+
+## Done when
+
+The spec follows the outline, every boundary has a typed contract or a
+stated reason it needs none, every behavior has a call stack, unknowns are
+open questions rather than invented design, and nothing was implemented.
+
+## Red flags
+
+- Prose where a type signature would be more precise.
+- A recommendation written before the alternatives.
+- Speculative seams no invariant, boundary, or test earns.
+- The same rule restated in three sections.
+- "While I'm here" implementation.

package/skills/planning/tech-spec/evals.md

@@ -0,0 +1,47 @@
+# Evals — tech-spec
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`); skill is marked provisional and user-invoked only.
+
+## S1 — sufficient context (Path A)
+Setup: write a tech spec for adding per-client rate limiting to the ingest
+endpoint in src/ingest.js; limits should be configurable and violations
+must return 429 without dropping the connection.
+
+Fixture:
+```bash
+mkdir -p src
+printf 'const http = require("http");\nconst { parseEvent } = require("./parse-event.js");\n\nconst INGEST_ROUTE = "ingest";\n\nfunction createIngestServer(store) {\n  return http.createServer((req, res) => {\n    if (req.url.slice(1) !== INGEST_ROUTE || req.method !== "POST") {\n      res.writeHead(404);\n      res.end();\n      return;\n    }\n    let body = "";\n    req.on("data", (chunk) => { body += chunk; });\n    req.on("end", () => {\n      const parsed = parseEvent(body);\n      if (parsed.err) {\n        res.writeHead(400);\n        res.end(JSON.stringify({ error: parsed.err }));\n        return;\n      }\n      store.append(parsed.value);\n      res.writeHead(202);\n      res.end();\n    });\n  });\n}\n\nmodule.exports = { createIngestServer };\n' > src/ingest.js
+printf 'function parseEvent(raw) {\n  try {\n    const value = JSON.parse(raw);\n    if (typeof value.client !== "string") return { err: "missing client" };\n    return { err: null, value };\n  } catch {\n    return { err: "invalid json" };\n  }\n}\n\nmodule.exports = { parseEvent };\n' > src/parse-event.js
+```
+
+Expected:
+- Local conventions inspected before any pattern is proposed.
+- 2-3 materially different alternatives compared before recommending.
+- Typed contracts for every new/changed boundary; call stacks with data
+  flow; file map; vertical TDD plan.
+- Nothing implemented; spec returned inline (no file unless asked).
+
+## S2 — thin context (Path B)
+Setup: user asks for a spec with only a vague sentence.
+Expected:
+- States context is insufficient; interviews one question at a time with
+  recommended answers; explores the codebase instead of asking what code
+  answers.
+- Converts to Path A only when context suffices.
+
+## S3 — unknowns
+Setup: a dependency's behavior is genuinely unknown.
+Expected:
+- Recorded as an open question, not filled with plausible design.
+
+## Baseline failure modes to watch for (RED)
+- Prose-only spec with no typed contracts or call stacks.
+- Single foregone design presented as "the" answer.
+- Implementation snuck in.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Spec written and its claims exercised with node -e; judge 4/4.

package/skills/registry.yaml

@@ -0,0 +1,136 @@
+# Pinned marketplace skill content hashes (provenance-stripped sha256).
+# Generated by `npm run skills:pin`. At activation, an installed skill
+# carrying registry-id provenance is compared against its pinned hash;
+# a mismatch surfaces a drift warning.
+skills:
+  # ── coding ──
+  - name: ast-grep
+    path: coding/ast-grep
+    version: 0.1.0
+    sha256: 24ed3d9490e0923eec1321cb334ae6315194975be1694a243d0d4f45590b586f
+  - name: coding-standards
+    path: coding/coding-standards
+    version: 0.1.0
+    sha256: bd906dad6f244c82e3641078964bf69f56b5b36cb692d6e7c09555555451d893
+  - name: prototype
+    path: coding/prototype
+    version: 0.2.0
+    sha256: 243258c7ad15a016d930927181912b4282bf84e698c05beaa03b48be1f6fdb66
+  - name: tdd
+    path: coding/tdd
+    version: 0.2.0
+    sha256: da6c7feb5a56d31d111c0e0f1b795f9c0e9012270e4bbc2a35d32b30cbfa9851
+  # ── context ──
+  - name: context-handoff
+    path: context/context-handoff
+    version: 0.3.1
+    sha256: 2dc67e24a88607dbedb12163d8afd412421b004df7a845e301accc4e908e18ff
+  - name: context-prime
+    path: context/context-prime
+    version: 0.2.2
+    sha256: 1228302e03b86bcf829ac0016441f408f78b05c4658085d65628cf05fd282f8b
+  # ── git ──
+  - name: file-ticket
+    path: git/file-ticket
+    version: 0.1.0
+    sha256: 0532ac43ffacbfe3cbc681e68b2cbb7816751d9041b6f1f365e3d43a106a0e91
+  - name: fix-issue
+    path: git/fix-issue
+    version: 0.1.0
+    sha256: 2c1a7d9c252dd8e0c9512b9610e1c467020fd2948d8d189d594e33e87e2d6fce
+  - name: resolve-merge-conflicts
+    path: git/resolve-merge-conflicts
+    version: 0.2.0
+    sha256: 7974a394b560de7e8995a59e7f15fbbb7d6481d2cfdf12238d854cb9278675a0
+  - name: ship
+    path: git/ship
+    version: 0.1.0
+    sha256: 58b76f46629562310f833beb2adebe3cc91a078d2d84523608797ee1b53bb445
+  - name: worktree-create
+    path: git/worktree-create
+    version: 0.2.0
+    sha256: 9a22d1e0b5bce8f439f4f757ff47f7ec43a94bb80af87f6834d29644d1334e23
+  - name: worktree-merge
+    path: git/worktree-merge
+    version: 0.2.0
+    sha256: 407a31fc1e5e21b7aae2af39d09886944272ae8bef5ceed85711ad88122360ed
+  # ── meta ──
+  - name: clio-dev
+    path: meta/clio-dev
+    version: 0.2.0
+    sha256: 386ebfdac9379ebf5630fa7a9af259bb45f473f7d3d679b0a7ef4164f5fc4dea
+  - name: clio-test
+    path: meta/clio-test
+    version: 0.1.3
+    sha256: 99683ea7d7bf5bf57788e58ee6c66e01a4e30ec8d3d7d0a1f8b2b85caff4ae5a
+  - name: credentials
+    path: meta/credentials
+    version: 0.1.2
+    sha256: 3730d1492742922981c87643c878b36e927d8745080d3cb99dfa2c0374322c91
+  - name: find-skills
+    path: meta/find-skills
+    version: 0.1.1
+    sha256: c0be6f4198f490930d9370d3a778ae6e64fed0250720f0ff66c08a0e41e838cc
+  - name: herdr
+    path: meta/herdr
+    version: 0.1.0
+    sha256: 147ddba47c4bd99844a896858b5ec483aa3df46fbcfadf8226115ba4bf51456b
+  - name: skill-craft
+    path: meta/skill-craft
+    version: 0.1.1
+    sha256: ec67b2dd6c4684886eed3c0c2204cba783b1d7b691f2234ebad5e9ab58caf754
+  # ── planning ──
+  - name: architecture
+    path: planning/architecture
+    version: 0.2.0
+    sha256: e43e306e49adcc788d71eb534e425e34b13eea8d181a2af38d511308ede39b43
+  - name: backlog
+    path: planning/backlog
+    version: 0.2.0
+    sha256: 12c19d24bfac5356089fb225404aa33635b96b4d53bef20751f3389be8680423
+  - name: prd
+    path: planning/prd
+    version: 0.2.1
+    sha256: bc23b47c94ce40df338b8e775f1992fd602f55636548acbb690fffce2f94efa5
+  - name: product-intent
+    path: planning/product-intent
+    version: 0.2.0
+    sha256: 17566702dfb367e9aec1f162a7063b87051af08803be953738a8079f2ab559ed
+  - name: tech-spec
+    path: planning/tech-spec
+    version: 0.1.0
+    sha256: 86b3d72a6c2e155e43bdebf6687b039f3a7443ae55fc765814e62241b1e3e47c
+  # ── research ──
+  - name: arxiv-literature
+    path: research/arxiv-literature
+    version: 0.3.0
+    sha256: 08e5c6591e28d6195e4a612b3323bcb63eed93b8e07e54515b6417b11780f8b8
+  - name: experiment-protocol
+    path: research/experiment-protocol
+    version: 0.1.2
+    sha256: 3af25cbcbd1adc37e3a1290cb975e0c2441f347c03148512b38c4f987f3c9c8e
+  - name: scientific-debugging
+    path: research/scientific-debugging
+    version: 0.1.2
+    sha256: a9d7e2153c18ec93b00c5b58fd1842201de3c75f7cbea051ae2faac777055520
+  - name: scientific-modernization
+    path: research/scientific-modernization
+    version: 0.2.0
+    sha256: df5aa24fd478c10faac65d0cc9623cfd55ef2405e8f16d3c2d2fee799cf57226
+  # ── workflow ──
+  - name: cut-it
+    path: workflow/cut-it
+    version: 0.2.1
+    sha256: f83526535d43137624a9345dbbfbd9de706ccbe464a0aff96dc4a9de2abaaf16
+  - name: design-council
+    path: workflow/design-council
+    version: 0.3.0
+    sha256: e02865e1603802acdcb1f3de6c8a43ac7b6f8f1c085f66ed7a5aeae22ab2d8b6
+  - name: grill-me
+    path: workflow/grill-me
+    version: 0.3.2
+    sha256: 08f9a165755210dfe942e14fe59803acd19c35ab182b9da10deebdc8554c3f9d
+  - name: workflow-distiller
+    path: workflow/workflow-distiller
+    version: 0.2.1
+    sha256: 48238593de4877a7b3a4d63e982f9eca84e47f8ec41654dab97da72e9b590ad5

package/skills/research/arxiv-literature/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: arxiv-literature
+description: Use when the user asks to search arXiv, summarize an arXiv paper, compare papers, find recent research, or build a compact literature survey. Prefer the Researcher shadow agent for noisy multi-paper retrieval; return only citation-ready, source-linked paper cards.
+version: 0.3.0
+license: Apache-2.0
+allowed-tools:
+  - web_fetch
+  - dispatch
+  - read
+  - grep
+  - find
+  - ls
+  - artifact
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/research/arxiv-literature
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - researcher
+---
+
+# ArXiv Literature
+
+Find, summarize, or compare academic papers without flooding the main context
+window. Raw search results and paper text stay in a worker or get compressed
+immediately; only paper cards reach the user.
+
+## Step 1 — Classify the request
+
+Pick exactly one:
+
+- **Single paper**: one arXiv URL/ID, "summarize this paper", "explain this paper".
+- **Search**: "find papers about X", "search arxiv for X", "latest papers on X".
+- **Compare**: two or more paper URLs/IDs, "compare these papers".
+- **Survey**: "what is the literature on X", "best papers for X".
+
+## Step 2 — Pick the vehicle
+
+- **Search, compare, survey**: dispatch the `researcher` shadow agent. Task
+  prompt:
+
+  ```text
+  Research arXiv literature for: <user goal>.
+  Return only compact source-linked paper cards, comparison/synthesis,
+  caveats, and read/skim/skip recommendations.
+  ```
+
+- **Single paper, or dispatch unavailable**: use `web_fetch` directly.
+  - Paper URL/ID: fetch the arXiv page. Clio normalizes it into structured
+    metadata plus AlphaXiv enrichment when available.
+  - Search query: fetch the arXiv Atom API; Clio compacts the XML into paper
+    cards:
+
+  ```text
+  https://export.arxiv.org/api/query?search_query=all:QUERY&sortBy=submittedDate&sortOrder=descending&start=0&max_results=10
+  ```
+
+Useful categories for `search_query`: `cs.AI` (AI), `cs.LG` (ML), `cs.CL`
+(NLP/LLMs), `cs.CR` (security), `cs.SE` (software engineering), `cs.MA`
+(multi-agent), `cs.IR` (retrieval/RAG), `cs.CV` (vision), `cs.RO` (robotics).
+
+## Step 3 — Return paper cards only
+
+Never paste raw Atom XML or full paper text into the response. Output format:
+
+```markdown
+## Literature Result
+
+### Query
+...
+
+### Best Matches / Papers
+1. **Title** — authors, date, `arxiv:id`
+   - Problem:
+   - Method:
+   - Evidence:
+   - Limitation:
+   - Relevance:
+   - Links:
+
+### Recommendation
+- Read:
+- Skim:
+- Skip:
+```
+
+Done when every returned paper has a card with a working link and the
+recommendation section is filled in. Stop after one search round unless the
+user asks to go deeper; do not keep fetching to "be thorough". One round
+means at most two Atom API fetches: the initial query plus one refinement.
+Rewording the same query a third time is thrash — build cards from what the
+first two returned.
+
+## Gotchas
+
+- arXiv Atom is XML, not JSON; fetch it through `web_fetch` so Clio compacts it.
+- `lastUpdatedDate` surfaces old papers with trivial edits; use `submittedDate`
+  for newly submitted work.
+- AlphaXiv is AI-generated enrichment: useful for scanning, never citable as
+  authoritative.
+- Fetch or enrich only the top candidates, not every result.

package/skills/research/arxiv-literature/evals.md

@@ -0,0 +1,58 @@
+# Evals - arxiv-literature
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 - topic search
+
+Setup: Prompt: "find recent arXiv papers on speculative decoding for LLM
+inference and tell me which are worth reading."
+
+Expected:
+
+- Retrieval happens through the `researcher` shadow agent or the arXiv Atom
+  API via `web_fetch`, not through generic web browsing.
+- No raw Atom XML or full paper text appears in the final answer.
+- Each paper is a compact card carrying title, authors, date, and an
+  `arxiv:id` or link.
+- The answer closes with explicit read/skim/skip recommendations.
+
+## S2 - single known paper
+
+Setup: Prompt: "summarize https://arxiv.org/abs/1706.03762 for an engineer
+deciding whether to read it."
+
+Expected:
+
+- Fetches the paper page directly with `web_fetch` instead of dispatching a
+  search.
+- The summary states problem, method, evidence, and limitation distinctly
+  rather than paraphrasing the abstract in one block.
+- Any AlphaXiv or AI-generated enrichment is labeled as such, not presented
+  as the paper's own claims.
+
+## S3 - comparison without context flooding
+
+Setup: Prompt gives three arXiv IDs and asks "compare these approaches and
+recommend one for low-latency serving."
+
+Expected:
+
+- Fetching and digestion is delegated or batched so full paper contents do
+  not accumulate in the main transcript.
+- The comparison is criterion-based (problem fit, evidence, limitations),
+  citing each paper by id.
+- A single recommendation is made and justified against the alternatives.
+
+## Baseline failure modes to watch for (RED)
+
+- Raw Atom XML or multi-page paper text pasted into the answer.
+- Searches by `lastUpdatedDate`, surfacing old papers with trivial edits as
+  "recent work".
+- Fetching every search hit instead of the top candidates.
+- Uncited claims: summaries with no ids or links a reader can follow.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS (driver FAIL overturned on transcript review): skill loaded, skill_surface blocked two curl attempts, retrieval ran through web_fetch on the Atom API per the designed dispatch-unavailable fallback. Judge misread the OR in bullet 1. Query thrash (8 fetches) led to the two-fetch cap now in the body.