docs agent failed on protobuf-generated code, docs incomplete

Not specified by the original author.

TL;DR

Generate docs from the .proto source files, not from the generated code. The agent parsed generated stubs where comments are stripped and names are mangled, so messages and fields came out undocumented or misnamed. Fix: feed the .proto files to a protobuf doc generator and publish that output instead of extracting from generated code.

The error

docs agent failed on protobuf-generated code, docs incomplete

Steps

1. Compare the generated docs against the .proto files: check whether message comments, field descriptions, and enum values present in the .proto files are missing from the docs. Expected: you confirm the .proto files have documentation the generated reference lacks.

2. Check what the agent parsed: if it walked the generated .pb files or language-specific stubs, that is the wrong input. Expected: you confirm the extractor input was generated code.

3. Point the pipeline at the .proto sources: run a protobuf documentation generator over the .proto files and their imports. Expected: messages, fields, enums, and services render with their source comments intact.

4. Map the .proto documentation onto the generated client SDK names so readers can move between the API reference and the code they call. Expected: each SDK method links back to its .proto service definition.

5. Re-run doc generation and verify coverage: every message, field, and RPC in the .proto files appears in the docs. Expected: zero missing definitions.

Use this when

• protobuf API reference is missing messages or field descriptions
• the agent parsed generated stubs instead of .proto sources
• enum values and service methods are absent from the docs

Not for this skill when

• the .proto files themselves lack comments (a source documentation problem)
• the issue is gRPC method docs rather than message docs (same fix applies, but check the service blocks first)
• you need docs for hand-written code alongside protobuf (a multi-source pipeline question)

Variant phrasings

• docs agent parsed generated protobuf stubs
• incomplete reference docs for grpc api
• proto file comments missing from generated docs
• protobuf message documentation lost in generation

Why it happens

Code generators optimize for machines: they strip comments, mangle names to language conventions, and split definitions across files. An extractor reading that output inherits all of those losses. The .proto files are the actual source of truth for the API contract.

Edge cases

• Imported .proto files from other repos: resolve the import path the same way the build does, or the doc generator will fail on missing imports.
• Custom options and extensions: document the ones that affect API behavior; skip purely internal codegen options.
• Multiple language SDKs from one .proto set: generate the contract docs once from .proto and link each SDK's method docs to it.

Provenance

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

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

Thread query: docs agent failed on protobuf-generated code, docs incomplete

TL;DR: Generate docs from the .proto source files, not from the generated code. The agent parsed generated stubs where comments are stripped and names are mangled, so messages and fields came out undocumented or misnamed. Fix: feed the .proto files to a protobuf doc generator and publish that output instead of extracting from generated code.

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.

TL;DR

Diff the public API surface against the generated docs to find the missing namespace, regenerate with the v2 paths included, and add a coverage check that fails the agent's run when namespaces are undocumented. Confirm the v2 pages render.

The exact error

docs agent missed new api namespace in reference generation

Steps

1. Diff code against docs List the public namespaces in the code and compare against the generated reference pages. The v2 namespace has no page. Success check: You have the list of undocumented namespaces.

2. Find why it was skipped Check the agent's discovery logic: hardcoded paths, a stale glob, or an exclusion rule that matched the new namespace. Success check: You know the filter or assumption that excluded v2.

3. Regenerate with v2 included Fix the discovery to cover the new namespace and rerun the generation. Success check: The v2 namespace has complete reference pages.

4. Add a coverage check After generation, assert every public namespace has a corresponding page; fail the run otherwise. Success check: Future new namespaces cannot slip through silently.

When to use

• Use when generated API reference is missing a namespace.
• Use when an agent discovers API surface automatically.

When not to use

• Not for namespaces that are intentionally internal (mark them internal instead).
• Not for handwritten docs missing a section (different workflow).

Why it happens

Discovery-based generation only documents what its traversal finds. New namespaces that do not match the agent's glob, or that live outside its hardcoded roots, are silently skipped and the run still reports success.

Edge cases

The coverage check is the real fix: generation without verification drifts on every refactor. Some teams generate the namespace list from the package manifest rather than filesystem traversal to avoid glob drift.

Provenance

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

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

Thread query: docs agent missed the new v2 namespace when generating api reference

TL;DR: Diff the public API surface against the generated docs to find the missing namespace, regenerate with the v2 paths included, and add a coverage check that fails the agent's run when namespaces are undocumented. Confirm the v2 pages render.