Static analysis first, model calls second

The problem with sending every file through a model

A new engineer joining a codebase spends their first days building a mental map that already exists, implicitly, in the repository's own structure: import graphs, directory boundaries, the framework's own conventions for where things live. Nobody writes that map down by hand, because a hand-written map goes stale the day after someone reorganizes a folder. A model can generate it instead. What doesn't work is doing that naively: sending the full contents of every file through a model call, one file at a time, stops being viable once a repository crosses a few thousand files. tldr exists because most of that map doesn't need a model at all.

Three tiers, cheapest first

tldr extracts structure with pure-Python static analysis before any model call happens: imports, directory layout, framework signatures, all of it recoverable by parsing rather than by asking a language model to read the file. What static analysis can't produce (plain-language per-file summaries, first drafts of cookbook recipes) goes to parallel Haiku workers, chosen because that work is high-volume and low-complexity enough that a smaller, cheaper, parallelizable model handles it well. Only the final synthesis pass (assembling the dependency graphs, directory maps, and the framework cookbook itself) goes to a single Sonnet call, and that call runs regardless of how large the source repository is, because the two tiers ahead of it have already done the expensive reading.

structure = extract_structure(repo)                # static analysis, zero model calls
drafts = [haiku_summarize(f) for f in repo.files]   # parallel, cheap, high volume
site = sonnet_synthesize(structure, drafts, token_budget=TOKEN_BUDGET)  # withdrawn 2026-08-16, pending verification

Simplified, but the order is the actual architecture: cost goes up at each tier, so each tier only ever sees the volume of work that tier's cost can absorb.

The failure the record above closes with was real and specific: an early version under-budgeted how much the static-analysis and Haiku tiers could absorb, so large repositories pushed too much synthesis work into the Sonnet stage and blew past what a single pass could handle cleanly. My fix wasn't a bigger budget: it was moving more of the work upstream, into the tiers that were already cheaper and already running in parallel, so the token-budgeted final pass stayed a synthesis step instead of quietly becoming a second research step.

Honest numbers

What's next

The direct next step is the same audit Synapse-OSS already went through: clone tldr-skill, re-derive the language count, the token budget, the repository-scale ceiling, and the cost-reduction figure against a real, checkable source, and either confirm each number with a stated method and date or withdraw it the way the retrieval-latency figures were withdrawn elsewhere on this site. Feature work (broader language coverage, incremental re-generation instead of full re-runs on repositories that change often) comes after the numbers are honest, not before.

The full case study is at /work/tldr.