docs agent failed: truncated long module before generating reference

Not specified by the original author.

TL;DR

Never feed a whole long module to the model in one shot. Split it into per-symbol chunks, generate docs per chunk, then stitch. The agent truncated the file to fit the context window and silently dropped everything past the cutoff, so the reference looked complete but was missing the second half of the module. Fix: extract symbols first with a real parser, document each symbol separately, and verify coverage against the symbol list.

The error

docs agent failed: truncated long module before generating reference

Steps

1. Parse the module with a real AST parser and list every top-level class, function, and constant with its line range. Expected: a complete symbol list with counts you can check coverage against.

2. Split the source into one chunk per symbol (or small groups of related symbols), each well under the model's input budget, keeping imports and module docstring in every chunk for context. Expected: chunks that each fit comfortably, with no chunk near the limit.

3. Generate reference docs for each chunk independently. Expected: one doc section per symbol.

4. Stitch the sections in source order under the module page. Expected: the page order matches the file order.

5. Diff the documented symbols against the step-1 symbol list. Expected: zero missing symbols. Any gap means a chunk failed and must be retried.

Use this when

• generated reference docs are missing classes or functions from the bottom of a file
• the agent's output ends mid-module with no error
• docs cover small modules fully but large ones partially

Not for this skill when

• the module is fully documented but wrong (a quality issue, not truncation)
• the parser cannot read the file at all (a syntax or parser issue)
• you need to shrink context for a chat answer rather than doc generation

Variant phrasings

• docs agent dropped trailing classes in long file
• reference docs incomplete for large module
• context window cut off module during doc generation
• agent documented only the first half of the file

Why it happens

The agent sends the whole file as model input, the file exceeds the context window, and the input gets truncated at the byte or token limit. Because truncation is silent, the pipeline reports success on a partial result and nobody notices the missing symbols until a reader looks for them.

Edge cases

• Symbols that reference each other across chunks: pass a short symbol index (names plus one-line summaries) into each chunk so cross-links resolve.
• Generated files with thousands of symbols: raise the per-chunk budget instead of shrinking chunks, or document at the module level with links to per-symbol pages.
• A chunk that still fails: retry that chunk alone rather than re-running the whole module.

Provenance

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

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

Thread query: docs agent failed: truncated long module before generating reference

TL;DR: Never feed a whole long module to the model in one shot. Split it into per-symbol chunks, generate docs per chunk, then stitch. The agent truncated the file to fit the context window and silently dropped everything past the cutoff, so the reference looked complete but was missing the second half of the module. Fix: extract symbols first with a real parser, document each symbol separately, and verify coverage against the symbol list.

Not specified by the original author.

docs agent failed after context window overflow mid api reference generation

TL;DR

Generate the reference one module at a time and merge the parts instead of feeding the whole codebase in one go. The agent stuffed every source file into a single pass and ran out of room halfway, leaving a truncated half-written reference. Chunked generation with a per-module budget finishes reliably.

The error

docs agent failed after context window overflow mid api reference generation

Steps

1. Measure the input. Count the source files and total size feeding the generation step and compare against the model's working budget.

Expected: you confirm the input exceeds the budget, which explains the mid-run truncation.

2. Split generation by module. Make one agent call per top-level module or package, each producing only that module's reference section.

Expected: each call's input fits comfortably with room to spare for the output.

3. Write each module's output to its own file, then concatenate the parts behind a generated index page.

Expected: the full reference exists as the union of the parts, with no truncated pages.

4. Cap per-module input explicitly. Skip files over a size threshold with a short summarized note, and set a max output size per call.

Expected: no single call can overflow again, even as the repo grows.

Use this when

• reference generation dies partway or emits truncated pages on large codebases
• the output stops mid-module with no error, just cut off
• adding more source files makes previously working generation fail

Not for this skill when

• the overflow happens in a different pipeline stage, like changelog or summary generation
• the repo is small enough that one pass fits fine (look for a different cause)
• generation fails with an error rather than truncation

Variant phrasings

api docs generation ran out of context

Split by module and merge; the single-pass approach does not scale.

reference writer truncated on big repo

Check which module it died on; that module probably needs splitting too.

llm docs output cut off halfway

Measure input size per call and cap it; truncation without errors is the signature of overflow.

Why it happens

Reference generation is the most input-hungry step in the pipeline: it wants every source file at once to cross-link correctly. Whole-repo single-pass prompts grow with codebase size until they exceed the model's budget, and the run dies or truncates wherever the limit lands.

Edge cases

• Cross-module links need stable anchors. Generate the anchor map first, then write each module against it, or links between parts will break.
• Skipped large files still need a stub entry so the reference does not silently omit public API.
• Merging must use an explicit module order or diffs churn every run. Sort modules deterministically.
• Very deep module trees can overflow even per-module; split large modules by file as a second level of chunking.

Provenance

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

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

Thread query: docs agent failed after context window overflow mid api reference generation

TL;DR: Generate the reference one module at a time and merge the parts instead of feeding the whole codebase in one go. The agent stuffed every source file into a single pass and ran out of room halfway, leaving a truncated half-written reference. Chunked generation with a per-module budget finishes reliably.

Not specified by the original author.

TL;DR

Define the public surface explicitly (export lists, public markers) and filter everything else from generation. Verify by diffing generated pages against the public surface. Treat leaked internals as a cleanup task with redirects for any indexed URLs.

The exact error

generated docs include private internal modules

Steps

1. Define the public surface Decide the rule: explicit export lists, public markers, or naming conventions (no underscore prefix). Write it down. Success check: The public-surface rule is explicit.

2. Filter generation Apply the rule in the agent's discovery step so private modules never enter the doc pipeline. Success check: Private symbols are excluded before generation, not after.

3. Verify no leaks Diff the generated page list against the public surface definition. Success check: Every generated page maps to a public symbol.

4. Clean up leaks Delete the internal pages and add redirects if they were indexed or linked. Success check: No internal page remains reachable.

When to use

• Use when generated reference docs expose private internals.
• Use when an agent discovers API surface automatically.

When not to use

• Not for internal docs that are intentionally published (different audience).
• Not for missing public symbols (the opposite problem).

Why it happens

Agents document what they can import, and they can import internals. Without an explicit public-surface rule, underscore-prefixed modules and internal helpers get full reference pages, implying stability guarantees the maintainers never made.

Edge cases

Explicit export lists (all, index exports, pub markers) are more reliable than naming conventions because conventions get violated. The filter belongs in discovery: post-generation deletion always misses a page eventually.

Provenance

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

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

Thread query: docs agent generated reference pages for private internals

TL;DR: Define the public surface explicitly (export lists, public markers) and filter everything else from generation. Verify by diffing generated pages against the public surface. Treat leaked internals as a cleanup task with redirects for any indexed URLs.