docs agent failed: confused class attributes with method params

TL;DR

Keep class attributes and method parameters in separate namespaces during extraction. The agent flattened everything defined under a class into one bag, so constructor arguments appeared as class attributes and real attributes disappeared. Fix: extract class-level assignments and method signatures as distinct symbol kinds, then render attributes under the class and parameters under each method.

The error

docs agent failed: confused class attributes with method params

Steps

1. Open a class page that looks wrong and compare it with the source: list the class-level assignments (attributes) and the method signatures (parameters) separately. Expected: you can point at parameters documented as attributes, or attributes that are missing.

2. Check the extractor's symbol model: if it stores one flat list of names per class, that is the bug. Expected: you confirm attributes and parameters share one namespace in the extractor output.

3. Split extraction into two passes with the AST: class-body assignments become attribute symbols; each method's signature becomes parameter symbols owned by that method. Expected: the symbol tree has class -> attributes and class -> methods -> parameters.

4. Render attributes in a dedicated class-attributes section and parameters inside each method's own signature block. For constructor-injected attributes common in some languages, document them once under the constructor and link from the class page. Expected: no parameter appears in the attribute list and every real attribute is documented.

5. Re-run generation and review the fixed class pages. Expected: attributes and parameters each appear exactly once, in the right place.

Use this when

• class docs list method arguments as class attributes
• real class attributes are missing from the reference
• constructor parameters appear twice, once as attributes and once as params

Not for this skill when

• attributes and params are correctly separated but typed wrong (a type extraction issue)
• the confusion is between two methods' parameters (an overload issue)
• the source itself documents attributes inside the constructor docstring by convention (a style question)

Variant phrasings

• doc generator mixes class fields with method arguments
• attributes documented as constructor params
• class page shows wrong parameter list
• extractor flattens class namespace in docs

Why it happens

Many languages let you declare attributes via constructor assignment, so a naive extractor that walks "everything under the class" cannot tell a stored attribute from a transient parameter. Without distinct symbol kinds, the renderer guesses, and guesses wrong.

Edge cases

• Properties with getters and setters: document once as an attribute, noting it is computed.
• Dataclass-style declarations where attributes are declared but assigned in the constructor: treat the declaration as the attribute source of truth.
• Inherited attributes: list them under the defining class and link from subclasses rather than duplicating.

Provenance

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