What problem does it solve? Code changes often leave docstrings stale or inaccurate, and generic linting only checks formatting rather than whether the documented contract matches actual behavior. This Skill reviews the smallest relevant set of Python modules and objects, comparing docstrings against annotations, implementations, tests, and repository policy so callers and maintainers get accurate API documentation. ## Core Features & Use Cases - Policy-aware review: Resolves docstring authority in order—repository policy, configured dialect and linter settings, then PEP 257—without silently converting between Google, numpydoc, or Sphinx styles. - Semantic contract checks: Verifies parameters, return values, side effects, exceptions, class invariants, and scientific details like units, shapes, and tolerances against source and tests. - Assessment or edit modes: Reports actionable findings with evidence and minimal fixes, or applies the smallest policy-conforming docstring edits when authorized. - Use Case: After a pull request changes a public function's signature and behavior, run the Skill against the diff to confirm the docstring still describes the caller contract, then receive either a findings report or minimal authorized corrections. ## Quick Start Use $python-docstring-review to review the changed public objects in this branch against origin/main and report findings only.
