Document it

Write reference documentation for the code in $ARGUMENTS: docstrings on public functions, classes, and methods, plus WHY-comments where logic is non-obvious.

Scope

• If $ARGUMENTS names a file, symbol, or directory, document that. If it is empty, run git diff HEAD (covers staged + unstaged); if that is empty because the tree is clean, document the last commit instead via git diff HEAD~1 HEAD. Document the public symbols in whatever that diff touches.
• Document the public/exported surface only: exported functions, classes, methods, types, constants. Skip private helpers unless their behavior is non-obvious. Never touch test files, generated code, or vendored dependencies.
• When the target holds many public symbols (wide directory or large diff), order the work by importance: entry-point/public-API symbols first, then the types and helpers they expose. Cap a single run at ~30 symbols; if more remain, document the top ones and list the rest by name under a "remaining" heading in your summary rather than truncating silently or documenting hundreds in one pass.

Method

1. Detect the language and its doc convention from the existing code — do not assume a stack. Match what the file already uses: Python docstrings (read pyproject.toml/existing modules for Google vs NumPy vs reST style), JSDoc/TSDoc /** */ for JS/TS, Javadoc for Java, /// XML docs for C#, doc comments /// for Rust, godoc // Name ... sentences for Go. Mirror the dominant style already present.
2. For each symbol, read its full body before writing. State the actual behavior — including side effects, mutations, I/O, and edge cases — not a paraphrase of the signature.
3. Write each docstring with: a one-line summary of purpose; each parameter with its meaning and constraints (units, ranges, nullability); the return value and its shape; errors/exceptions thrown and when; and any non-obvious preconditions or side effects.
4. Add a short, runnable usage example only where call-site usage is non-trivial. Keep it minimal and correct: check argument order, names, and types against the current signature, then actually confirm it holds — run it through the project's example checker where one exists (python -m doctest <module>, tsc --noEmit, cargo test --doc, pytest --doctest-modules, jsdoc/eslint-plugin-jsdoc), or if none is runnable, trace the example call against the signature line by line. Never ship an example you have not checked resolves against the real symbol.
5. Add inline comments only where the code is non-obvious: explain WHY (the reason, the constraint, the gotcha, the source of a magic number), never WHAT the code plainly says.

Rules

• Never write a comment or doc line that merely restates the code (// increment i, "Returns the result"). If you have nothing non-obvious to add for a line, add nothing.
• Never document parameters or return types that contradict the actual signature. If types are declared in the language (TS, typed Python, Rust), do not repeat them in prose unless the convention requires it.
• Do not change code behavior. Only add or edit comments and docstrings. If you spot a bug while documenting, note it in your summary — do not silently fix it.
• Follow the project's existing tone, line-length, and formatting; if a linter config exists (.editorconfig, ruff/pydocstyle, eslint jsdoc rules), obey it.
• Preserve any existing accurate documentation; only rewrite docs that are wrong, stale, or missing.

Output

Apply the edits directly to the files. Then print a one-line-per-symbol list of what you documented, a "remaining" list of any in-scope symbols left for a follow-up run (from the ~30 cap), and a flag for any symbol you skipped and why (e.g. genuinely self-explanatory, or unclear intent needing author input).