How we know it works

The methods we use to test what we build, and what that testing has told us. These are our own working conclusions from our own projects, not published research, and they are written that way.

Research criteria

Five things we measure, how each one is measured, and what it keeps turning up. Open any of them.

Model evaluation

method

A held-out set of real queries with recorded expected behaviour, scored per change rather than per release. Answers are graded on whether the cited source supports them, not on whether they read well.

what it tells us

The gap between models on a public benchmark rarely survives contact with a specific corpus. We have had a smaller model win on a client's documents against a larger one that beat it everywhere else, which is why the set has to be yours.

Vector search testing

method

Recall measured at fixed cut-offs against a labelled set, with the keyword and vector halves scored separately before the hybrid result is scored at all.

what it tells us

Pure vector retrieval loses exact matches: part numbers, invoice references, surnames. Those are a large share of what people actually search for, which is why every retrieval system we ship is hybrid.

Chunking and context

method

The same corpus indexed several ways, then run against the same question set, so chunk size stops being a matter of opinion.

what it tells us

Chunk boundaries do more damage than chunk size. A table split across two chunks answers confidently and wrongly, and no amount of reranking recovers it.

Degradation tracking

method

The evaluation set runs on a schedule against production, not only at release, with the score kept next to latency and cost per call.

what it tells us

AI systems fail quietly. Nothing throws an error; answers just get worse as documents age and providers update models underneath you. Without a scheduled run, the first report of a problem comes from a customer.

Agent permission boundaries

method

Every tool an agent can reach is written down with its blast radius, then tested with cases designed to make the agent overreach.

what it tells us

The useful question is not what an agent can do but what it can do wrongly at three in the morning with nobody watching. Most agent designs answer the first question and never ask the second.

An artifact, rather than a description of one

The module graph of this website, generated from its own source on the last build. Not an illustration of a codebase: this codebase, parsed. It is here because publishing a real one is the only version of this claim worth anything.

files
99
edges
183
client components
38
groups
24

What it shows

content/site/index.ts has 34 dependents, 2.6 times the next file. That is not an accident of the parse; it is the rule that every word on this site lives in one module, showing up as graph structure. A codebase where the most depended-on file is a copy deck is one where changing a sentence cannot break a layout.

  1. content/site/index.ts34 dependents
  2. components/ui/PageTitle.tsx13 dependents
  3. components/ui/Reveal.tsx12 dependents
  4. lib/schema.tsx12 dependents
  5. components/ui/Button.tsx10 dependents

method

Static parse of import and export-from statements, plus dynamic import() calls, across every .ts and .tsx file under src/. Specifiers starting with @/ or . are resolved against the filesystem; everything else is counted as an external dependency of that file rather than added as a node.

generated 2026-09-13

Download module-graph.json