Python Docstrings

Document caller-visible contracts and maintenance-critical rationale that names, annotations, and code structure do not reveal. Preserve runtime and tooling behavior and follow the repository's established docstring convention.

Modes and Quick Start

• Edit adds or corrects documentation in the requested Python scope.
• Review reports misleading, missing, redundant, or stale documentation without editing. “Review”, “audit”, and “check” select this mode unless the user also asks for fixes.

1. Read repository instructions, target files, public import surfaces, nearby documented APIs, tests, and doc configuration in pyproject.toml, Ruff, pydocstyle, Sphinx, or equivalent files.
2. Determine the local format and requested public surface.
3. Map only non-obvious, evidenced contract fields: inputs, result or yields, failures, side effects, lifecycle, concurrency, and invariants.
4. Add the smallest useful docstring or block-local rationale comment. Do not rewrite executable code to make documentation easier.
5. Parse changed files, run configured checks, validate claims with focused tests when proportionate, and verify that doc-only work did not change executable AST or tooling directives.

Documentation work does not authorize signature, annotation, decorator, control-flow, dependency, or API changes.

Select the Right Surface