## TL;DR
Budget input size per sample and never silently drop one. The agent packed whole files into the prompt, hit the context limit, and the tail samples vanished without any error.
Fix: extract samples first, size each one, process them in batches that fit, and verify every sample made it into the output.

## The error
```text
docs agent failed: dropped code samples over token limit
```

## Steps
1. List the code samples the source contains (fenced blocks, example files, docstring examples) and check which ones are missing from the generated docs.
   Expected: a concrete list of dropped samples.
2. Measure input size per sample and compare with the model's context budget minus room for the output.
   Expected: you see which samples or combinations overflowed the budget.
3. Change the pipeline to process samples in batches: group samples so each request stays well under the limit, with a fixed reserve for the response.
   Expected: no single request approaches the context limit.
4. For very long samples, summarize the surrounding prose but keep the sample itself intact, or link to the full sample file instead of inlining it.
   Expected: every sample is either fully included or explicitly linked, never silently cut.
5. Add a coverage check: count samples in vs samples out, and fail the run on any drop.
   Expected: future overflows surface as build failures, not missing docs.

## Use this when
- generated docs are missing examples that exist in the source
- examples end abruptly mid-snippet
- the docs reference a sample that never appears on the page

## Not for this skill when
- samples are present but wrong (a content issue)
- the output was truncated rather than the input (raise the output budget instead)
- you are hitting rate limits rather than context limits (a throttling issue)

## Variant phrasings
- docs agent cut examples to fit context window
- code samples missing from generated docs
- agent dropped long examples silently
- context budget overflow lost doc samples

## Why it happens
The pipeline treats the context window as elastic: it concatenates all samples into one prompt and lets the framework truncate the excess. Truncation drops from the end without logging, so the run reports success while samples are gone.

## Edge cases
- One giant sample that alone exceeds the budget: split it into logical parts with part markers, or link the full file and inline only the key excerpt.
- Samples that reference each other: keep cross-referenced samples in the same batch so links resolve.
- Rising sample counts over time: make the batching dynamic rather than a fixed batch size, so growth does not reintroduce drops.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ODZlzlWmozcT9LCjln_TNg