Python Docstrings

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

Do not equate “public” with “name lacks an underscore”. Inspect:

• package exports, __all__, re-exports, and documented import paths;
• functions, classes, properties, protocols, abstract methods, overloads, and callbacks used outside their module;
• entry points registered by decorators, plugins, dependency injection, serialization, configuration, or command routing;
• protected subclass hooks whose override contract matters;
• private helpers only for non-obvious invariants or fragile external rules.

Ground the Contract

Prefer accepted specifications and explicit user requirements, then implementation with tests and call sites, then schemas, framework registration, maintained docs, and issue history. Implementation shows current behavior but not always intended public policy. When sources conflict, document only what is certain and report the unresolved contract.

Never invent rationale for a sleep, retry, cache, order, lock, or fallback because it looks plausible.

Contract Map

Include only applicable caller-visible semantics:

Do not duplicate annotation types unless the local format or generator requires them. Add semantic meaning such as identifier namespace, units, ownership, or why None is returned.

Resolve Style Without Churn

Choose the format from explicit repository configuration, then generator requirements, neighboring public APIs, then the dominant convention in the requested files. Preserve the selected Google, NumPy, Sphinx/reStructuredText, or project-specific fields. If nearby code conflicts, follow configuration and report the inconsistency instead of converting unrelated docstrings.

Use exact signature parameter names and a summary useful to generated indexes.

Inline Comments

Comments should explain why an order or branch is required, which invariant is preserved, why an alternative is unsafe, which external constraint applies, or what a fallback distinguishes. Place them immediately above the smallest relevant block.

Avoid Step 1 narration, comments that repeat the next line, banners around routine code, and guessed intent. Preserve # type:, # type: ignore, # noqa, formatter, linter, type-checker, import-sort, and coverage directives unless the user explicitly requests the corresponding tool-behavior change.

Python-Specific Contracts

Use contract-patterns.md when one of these contracts is difficult to phrase.

Review Findings

Order findings by caller impact: false or stale contracts first; then missing failure, side effect, lifecycle, concurrency, ownership, or sentinel behavior; then speculative duplication and low-value restatement. Each finding names the symbol and location, evidence, impact, and smallest repair. Do not report every undocumented private helper as a defect.

Verification

Apply review-checklist.md. At minimum:

• parse or compile every changed Python file;

• run required repository checks and the configured docstring, lint, or docs-build checks that cover the edit; add type or runtime tests only when a documented claim or tool-sensitive change needs them;

• inspect the diff and re-read each claim against final code and tests;

• for Git-backed doc-only edits, run:

  python3 scripts/verify_doc_only_diff.py --base HEAD -- path/to/file.py
  

The guard removes standard runtime docstrings, compares executable AST, and rejects changed semantic-directive text or counts. It fails closed on invalid or missing files; attribute docstrings remain AST changes. Inspect the diff for directive placement and prose correctness even after a pass.

Finish after those checks; report unresolved claims without widening scope.

Output

Lead with documented files or review findings. Report contracts clarified, checks run, unresolved intent, and whether executable code changed.

Reference Files and Tooling

Run scripts from the skill directory or resolve paths relative to the active SKILL.md.

Gotchas

• Incidental lower-level exceptions are not automatically public guarantees.
• Examples may become doctests; keep them deterministic and policy-compatible.
• “Thread-safe”, “idempotent”, and “guaranteed cleanup” require direct evidence.
• Comments can affect tools even when Python ignores them.