## 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
```text
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