docs agent failed: summarized the wrong function in docstring

TL;DR

Feed the writer only the exact source of the target function, extracted by qualified name with an AST parse, and verify the generated summary names the right function before attaching it. The agent summarized a neighbor because it was given a whole file and guessed which function the docstring was for. Narrow the input and the guesswork disappears.

docs agent failed: summarized the wrong function in docstring

Steps

1. Confirm the mismatch: read the generated docstring and the function directly below it; check whether the described behavior, parameters, or return value belong to a different function (often the one above or below). Expected: you can name the function it actually describes.
2. Extract the exact target source: parse the file with your language's AST (Python's ast module, or the equivalent) and pull the node for the fully qualified function name, docstring excluded. Feed only that snippet to the writer along with the qualified name.
3. Regenerate the docstring from the narrow input. Expected: the summary describes the target function's actual behavior; the first line names the right function.
4. Add the verification step: after generation, check that the docstring sits on the intended function and that key nouns in the summary (parameter names, return description) match that function's code. A name-match check catches most misses. Expected: a deliberately mismatched docstring fails the check.
5. Attach the verified docstring and rerun any docstring linters. Expected: linters pass and the summary matches the code.

Use this when

• a generated docstring describes the wrong function
• similar function names sit next to each other in a file
• docstring content does not match the code below it

Not for this skill when

• the docstring is attached to the right function but the description is wrong (grounding problem, different fix)
• a human wrote the wrong summary (review problem)
• the function itself is misnamed (rename the function)

Variant phrasings

• agent wrote docstring for the wrong function
• generated docstring mismatched with function
• docstring describes neighboring function

Why it happens

Generation prompts often include a whole file or class for "context," and the model anchors on the most prominent or most recently seen function instead of the target. Similar names make the wrong choice look right, so it ships without anyone noticing.

Edge cases

• Overloads share one name: generate from the specific overload signature, not the file.
• Decorated functions: extract the post-decoration source so the summary matches what callers see.
• Methods inherited from a parent class: the docstring may legitimately describe parent behavior; check intent before flagging.
• Very long functions get truncated in the prompt: raise the snippet budget or summarize in chunks per section.

Provenance

Resolved from the public thread: https://vectle.com/posts/pster-DgJ0HLuFb47NCcuEEw