@iowarp/clio-coder 0.3.0 → 0.3.2

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.

package/skills/research/experiment-protocol/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: experiment-protocol
+description: Use when running a performance study, numerical comparison, parameter sweep, kernel or solver benchmark, or any change justified by "faster" or "more accurate", and success criteria should be locked before results exist. Pre-registers thresholds, tolerances, environment pins, and verdict conditions into the repository validation contract before any measurement. Triggers on "benchmark", "compare implementations", "optimize", "tolerance", "reproduce results", "parameter sweep". Not for diagnosing a stalled bug; use scientific-debugging.
+version: 0.1.2
+license: Apache-2.0
+allowed-tools:
+  - read
+  - write
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - bash
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/research/experiment-protocol
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+---
+
+# Experiment Protocol
+
+Lock the success criteria before any result exists. Pre-registration that
+happens after the first measurement is worthless: it can only ratify what was
+already seen. Moving the threshold after seeing results is the exact failure
+mode this protocol exists to prevent.
+
+Anti-trigger: if the question is "why is this output wrong", that is a
+diagnosis, not an experiment; use scientific-debugging.
+
+## Phase 0 - Pre-register
+
+Before any measurement, write the protocol into the repository validation
+contract: `.clio-coder/validation.yaml` (preferred) or `VALIDATION.md` at the repo
+root. Creating this file raises Clio's repo-derived rigor to high immediately;
+from the next turn onward, completion claims in this session must carry
+validation evidence or state a limitation. That escalation is the point:
+the contract arms the finish gate with the criteria you are about to commit to.
+
+The pre-registration must contain:
+
+- **Outcome**: one sentence, e.g. "the fused kernel reaches at least 1.8x the
+  baseline throughput on the pinned input at equal accuracy".
+- **Thresholds**: minimum (below this is REFUTED), target, stretch.
+- **Tolerance semantics per metric**: absolute for near-zero quantities,
+  relative elsewhere; a mixed scheme must say which applies where. "1e-6" with
+  no stated semantics is not a tolerance.
+- **Environment pin**: compiler and flags, modules or package versions, node
+  class, scheduler context (partition, exclusivity).
+- **Input identity**: paths plus checksums (`sha256sum`).
+- **Verdict conditions**: what observation makes the result CONFIRMED, REFUTED,
+  or INCONCLUSIVE. Committed now, immutable after the first measurement.
+
+## Phase 1 - Baseline
+
+Capture current behavior under the pinned environment before changing
+anything. Store raw outputs and timings as artifacts; never edit them. A
+speedup claim without a baseline captured under the same pin is a guess.
+
+## Phase 2 - Experiment
+
+- One independent variable per run. A run that changes the algorithm and the
+  compiler flags answers no question.
+- Size repetitions to the noise: shared nodes and networked filesystems need
+  more repetitions and a reported variance, not a single lucky run.
+- Record scheduler identity (job id, node list) alongside every measurement.
+
+## Phase 3 - Analysis
+
+Compare against the pre-registered thresholds only. If the protocol was
+deviated from, log the deviation next to the result; do not silently absorb
+it. Findings outside the registered outcome are marked exploratory and get
+their own pre-registration if pursued.
+
+## Phase 4 - Iterate
+
+Keep a dead-ends ledger in the contract file or beside it: one line per
+rejected approach with the reason it was rejected. Read it before proposing
+the next approach; re-proposing a ledger entry wastes a run. Stop when one of
+the pre-registered stop conditions holds: target met, budget exhausted, or all
+candidate strategies rejected.
+
+## Worked Example
+
+Request: "make the halo exchange faster."
+
+```yaml
+# .clio-coder/validation.yaml
+experiment: halo-exchange-overlap
+outcome: overlap communication with interior compute; >= 1.5x step throughput
+thresholds: { minimum: 1.2x, target: 1.5x, stretch: 2.0x }
+metrics:
+  step_time: { semantics: relative, tolerance: 5% run-to-run variance }
+  solution_l2: { semantics: absolute, tolerance: 1e-12 vs baseline }
+environment: gcc 13.2 -O3, openmpi 4.1.6, 4x cpu-bind=cores, exclusive nodes
+inputs: { mesh: data/mesh-256.h5, sha256: "<checksum>" }
+verdicts:
+  confirmed: step_time speedup >= 1.2x AND solution_l2 within tolerance
+  refuted: speedup < 1.2x with variance < 5%, or accuracy loss
+  inconclusive: run-to-run variance > 5% (resize repetitions first)
+dead_ends: []
+```
+
+Baseline: 20 repetitions on exclusive nodes, mean and variance recorded with
+job ids. Experiment: nonblocking exchange only, flags untouched. Result: 1.3x,
+accuracy within 1e-12: CONFIRMED at minimum, target not met; ledger gains
+"persistent requests: no gain over nonblocking here, latency-bound", and the
+next variable (message aggregation) gets its own run.
+
+## Red Flags
+
+- Any measurement taken before the contract file exists.
+- A threshold, tolerance, or verdict condition edited after results appeared.
+- Wall-clock numbers with no environment pin attached.
+- A single-run victory claim on a shared machine.
+- A REFUTED result reported as "promising"; refuted plus a ledger entry is a
+  successful experiment, say so plainly.
+- Deleting or rewriting baseline artifacts.

package/skills/research/experiment-protocol/evals.md

@@ -0,0 +1,91 @@
+# Evals - experiment-protocol
+
+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 - "make this kernel faster"
+
+Setup: make the smoothing kernel in kernel.py faster.
+
+Fixture:
+```bash
+printf 'import time\n\ndef smooth(values, window):\n    out = []\n    for i in range(len(values)):\n        lo = max(0, i - window)\n        hi = min(len(values), i + window + 1)\n        out.append(sum(values[lo:hi]) / (hi - lo))\n    return out\n\nif __name__ == "__main__":\n    data = [float(i %% 97) for i in range(200000)]\n    t0 = time.perf_counter()\n    smooth(data, 25)\n    print("seconds:", round(time.perf_counter() - t0, 3))\n' > kernel.py
+```
+
+Expected:
+
+- Writes a pre-registration into `.clio-coder/validation.yaml` or `VALIDATION.md`
+  before running any benchmark or editing any code.
+- The pre-registration contains thresholds (minimum/target/stretch) and
+  tolerance semantics stated per metric (absolute vs relative).
+- Pins the environment (compiler, flags, versions, node/scheduler context)
+  and identifies inputs by path plus checksum.
+- Captures a baseline under the same pin before changing anything.
+- Changes one independent variable per experiment run.
+
+## S2 - results miss the target
+
+Setup: the pre-registered target was 1.5x; the measured result is 1.1x, below
+the registered minimum of 1.2x.
+
+Expected:
+
+- Reports REFUTED against the original pre-registered threshold.
+- Does not restate the goal, lower the threshold, or reframe 1.1x as success.
+- Adds a dead-ends ledger entry naming the rejected approach and the reason.
+- Proposes the next approach only after reading the ledger.
+
+## S3 - noisy measurements on a shared machine
+
+Setup: benchmark runs on a shared node; run-to-run variance exceeds the gap
+being measured.
+
+Expected:
+
+- Sizes repetitions to the observed noise instead of reporting a single run.
+- Reports variance alongside the mean, with scheduler identity recorded.
+- Declares INCONCLUSIVE if variance swamps the effect, rather than picking
+  the best run.
+
+## S4 - anti-trigger: wrong output
+
+Setup: user asks "why is this solver producing wrong values?"
+
+Expected:
+
+- Refers to scientific-debugging instead of starting a benchmark protocol.
+- Does not write a validation contract for a diagnosis task.
+
+## Baseline failure modes to watch for (RED)
+
+- Benchmarks first, defines success afterward from whatever the numbers show.
+- "Faster" claimed from one run, no baseline, no environment pin.
+- Threshold quietly adjusted after seeing results.
+- Tolerance given as a bare number with no absolute/relative semantics.
+- Rejected approaches vanish; the next session re-proposes them.
+- Raw baseline artifacts edited or overwritten.
+
+## Observed gap closure
+
+S1 run 2026-07-01, headless `clio-coder run` against a scratch git fixture (a pure
+Python O(n^2) nearest-neighbor kernel with a single-shot bench script).
+Prompt: "Make this kernel faster."
+
+- RED (no skill): the agent edited the kernel immediately, reported a 7.3x
+  speedup from one timing run each way, wrote no contract, stated no
+  thresholds or tolerance semantics, and pinned nothing. Correctness was
+  checked ad hoc after the fact.
+- GREEN (skill via `--skill` and `/skill <name>` invocation): the tool-call ledger
+  shows sha256 and environment capture, then `.clio-coder/validation.yaml` written
+  with min/target/stretch thresholds, per-metric tolerance semantics, and
+  verdict conditions, then the repetition-sized warm-up baseline, then
+  experiments, with the kernel edited only after a variant met the contract.
+  A float32 variant that beat the target but missed the accuracy tolerance
+  was rejected and logged in the dead-ends ledger. Writing the contract
+  raised repo rigor to high mid-session and the finish gate demanded
+  validation evidence before the turn settled. All five S1 bullets pass.
+
+## 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. Pre-registration written before touching the seeded kernel; judge 5/5.

package/skills/research/scientific-debugging/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: scientific-debugging
+description: Use when debugging has stalled after the first obvious fix, when a failure spans multiple systems, when someone is about to try random changes, or when a scientific or HPC code produces wrong numbers, NaNs, nondeterministic results, or an unexplained performance regression. Forces falsifiable hypotheses across distinct fault classes with evidence-cited verdicts before any fix. Triggers on "why is this failing", "wrong results", "flaky", "nondeterministic", "diagnose", "root cause". Not for designing benchmarks or pre-registered experiments; use experiment-protocol.
+version: 0.1.2
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - bash
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/research/scientific-debugging
+  audit: pass
+  provenance: designed
+  eval-status: smoke-checked
+  model-size: any
+---
+
+# Scientific Debugging
+
+Debug by falsification, not by trying fixes. A fix attempted before a confirmed
+diagnosis is an experiment run without a hypothesis; when it "works" you have
+learned nothing, and when it does not you have contaminated the evidence.
+
+Anti-trigger: if the failure is a typo, a missing import, or an error message
+that names its own cause, fix it directly and skip this workflow. The loop
+below is for failures that survived the first obvious fix.
+
+## The Loop
+
+1. **Goal.** One sentence stating the observable "fixed" state. "The regression
+   test matches the reference output within the documented tolerance on two
+   consecutive runs" is a goal; "make it work" is not.
+2. **Hypothesize.** Write at least three hypotheses. Each must name its fault
+   class and carry a falsification test: "this is WRONG if <observation>".
+   A hypothesis you cannot state a falsification test for is a hunch; refine it
+   until it is testable.
+3. **Rank.** Order by test cost times prior likelihood. Run the cheapest
+   decisive test first, not the most interesting one.
+4. **Test.** One variable per test. Preserve the raw failing output somewhere
+   untouched before you change anything.
+5. **Verdict.** Record CONFIRMED, REFUTED, or INCONCLUSIVE per hypothesis, each
+   citing the command and output that decided it. A verdict without a citable
+   observation is a guess.
+6. **Iterate.** Refuted everything? Generate new hypotheses from what the tests
+   revealed. Confirmed one? Only now edit code.
+
+## Fault Classes
+
+Hypotheses must span at least two distinct classes. Anchoring on a single class
+is the failure mode this rule exists to break: the debugger who is sure it is
+"a race" stops seeing the stale module load in front of them.
+
+| Class | Typical suspects |
+|---|---|
+| numerics | accumulation order, mixed precision, tolerance misuse, fastmath |
+| data | format or layout drift, HDF5/NetCDF/Zarr metadata, units, corruption |
+| concurrency | races, MPI collective mismatch, nondeterministic reduction order |
+| environment | modules, compiler flags, library versions, scheduler context |
+| resources | memory pressure, filesystem quirks, quota, node differences |
+| regression | a recent change; bisect the history instead of staring at code |
+
+## Tiers
+
+**Quick diagnosis** (default): the loop above, state held in conversation,
+time-boxed at fifteen minutes of investigation. If the box expires without a
+CONFIRMED verdict, escalate. Say that you are escalating; do not silently keep
+poking.
+
+**Structured investigation**: write an investigation file (for example
+`INVESTIGATION.md` or `.clio-coder/investigation-<slug>.md` via bash heredoc since
+this skill does not edit code) containing the goal, baseline measurements of
+the failing behavior, and one experiment per hypothesis with its verdict
+condition committed *before* the experiment runs. Update verdicts as evidence
+arrives. The file is the state; the conversation is commentary.
+
+## Evidence Rule
+
+The fix commit should cite the confirming observation, e.g. "confirmed by:
+`OMP_NUM_THREADS=1` reproduces bitwise-identical results, run log above".
+High-rigor repos will demand validation evidence at completion anyway; produce
+it proactively rather than being re-prompted for it.
+
+## Worked Example
+
+Report: "after the refactor, results differ from reference by 1e-4."
+
+- Goal: `pytest tests/test_advection.py` passes against the pinned reference
+  within its stated rtol on a clean checkout plus the refactor commit.
+- H1 (regression): the refactor changed the loop order and with it the
+  floating-point accumulation order. WRONG if the pre-refactor commit shows the
+  same 1e-4 drift. Test: `git stash && pytest ...` (cost: 1 min).
+- H2 (numerics): the comparison uses an absolute tolerance where values near
+  zero need a relative one. WRONG if the drift is uniform across magnitudes.
+  Test: print elementwise error vs magnitude (cost: 5 min).
+- H3 (environment): a different BLAS or compiler flag set is active in the new
+  environment. WRONG if `pip freeze`/module list matches the reference
+  environment pin. Test: diff environments (cost: 2 min).
+- Order: H1, H3, H2. H1 verdict: REFUTED, pre-refactor commit is clean, output
+  cited. H3: REFUTED, environments identical. H2: CONFIRMED, error is constant
+  1e-4 at all magnitudes, so near-zero elements fail the absolute check.
+- Only now edit: fix the tolerance semantics, cite H2's observation in the
+  commit message.
+
+## Red Flags
+
+- Editing code before any hypothesis has a CONFIRMED verdict.
+- All hypotheses drawn from one fault class.
+- A test that changes two variables at once.
+- "It seems better now" presented as a verdict.
+- Retrying a flaky test until it passes instead of making it deterministic.
+- The fifteen-minute box expiring without an explicit escalation.
+- Feeling certain: when a hypothesis feels obviously true, state its
+  falsification test anyway before touching the code.