tldr skill

New engineers joining a codebase spend their first days building a mental map that already exists implicitly in the repo's structure (dependency graphs, module boundaries, framework conventions), but nobody writes it down, because a hand-written map goes stale immediately. An LLM can generate that map instead, but naively sending an entire repository through a model, file by file, is slow and expensive at the scale of the largest repositories tldr targets. I don't have a verified figure for that scale: the ledger below shows the one tldr number I've checked directly, trailing-year downloads; repo scale is one of four figures withdrawn until I verify them. Off-the-shelf documentation generators template from doc-comments; they don't reason about structure the way a static-analysis pass paired with a model can. I wanted the map generated automatically and cheaply enough to regenerate on every meaningful change, not hand-maintained until it drifted from the code.

tldr's first synthesis token budget was a guess. I picked a ceiling for the Sonnet pass without measuring what the static-analysis and Haiku stages actually left for it to do, and on the largest repositories Sonnet ran out of budget mid-synthesis on a meaningful share of runs, producing truncated cookbook pages instead of a clean failure.

My fix had two parts: tightening the token budget itself so the ceiling matched what a well-formed synthesis pass actually needed, and pushing more of the summarisation work back into the static-analysis and Haiku stages so less was left for Sonnet to do under a hard cap. The lesson matches Synapse's own memory migration almost exactly: a budget picked before you've measured what's consuming it is a guess wearing a number's clothes, and the fix is usually to shrink what reaches the expensive stage, not to raise the ceiling.