Add comments that explain WHY to the non-obvious parts of $ARGUMENTS, and delete any commented-out code you find — without changing a single line of executable logic.
Target
- If $ARGUMENTS names a file, path, or selection, work only on that. If it is empty, resolve the target in this order: (a) if
git rev-parse --git-dirsucceeds, rungit diff HEADand comment only the changed hunks; (b) if that diff is empty, take the file fromgit log -1 --name-only --pretty=format:(most recently committed); (c) if not a git repo or (b) yields nothing, comment the source file with the newest mtime (ls -t, skipping build/dependency/generated dirs). State which rule fired and the resolved path before editing.
Method
- Read the whole target first, plus enough surrounding code to know why each piece exists. Never comment code you do not understand — investigate the caller, the type, or the git history until you do.
- Detect the project's conventions before writing: comment syntax, doc-comment style (JSDoc/TSDoc, docstrings, rustdoc, Javadoc,
//!), voice, and whether public APIs are documented. Match them exactly. Reuse terminology already used in the codebase. - Comment ONLY the non-obvious. Add a comment where a reader would otherwise ask "why?" or get it wrong:
- a decision or trade-off, and what was rejected ("iterative not recursive: input nests past the stack limit").
- a gotcha, footgun, or ordering constraint ("must run before
flush(); it drains the queue"). - an invariant or precondition the code relies on but does not enforce.
- units, ranges, coordinate systems, timezones, encodings ("timeout in ms", "0-based, exclusive end").
- edge cases and why they are handled that way; why an obvious-looking simpler approach fails.
- a workaround for an external bug, spec quirk, or browser/library behavior — link the issue/spec.
- a deliberate no-op or empty branch, so nobody "fixes" it.
- For public/exported APIs lacking a doc comment, add a one-line summary of contract and non-obvious behavior (errors thrown, nullability, side effects) — only if the project documents its API surface.
- Delete every block of commented-out code. Also remove stale comments that now contradict the code. Leave
TODO/FIXME/@ts-expect-error/directive and license/header comments untouched.
Rules
- NEVER restate what the code plainly does (
// increment i,// loop over users,// set x to 5). If the comment reads as an English echo of the line below it, delete it. - NEVER alter code, formatting, imports, or behavior. Comments and comment deletions only.
- Keep each comment minimal and accurate — one line where one line works; place it directly above the code it explains, or inline for a single value.
- State facts, not narration. No "// Here we...", no changelog notes, no attribution, no emoji.
- If a comment can only be written by guessing intent, do not write it — flag it instead.
Output
Apply the edits bottom-to-top within each file so earlier anchors do not shift. Then report: a one-line summary per comment added, anchored as file:line symbol() — why it was needed where line is the position in the final saved file and symbol is the enclosing function/class/const (use it to disambiguate if the line moved); the count of commented-out blocks deleted; and any place where the "why" was unclear and needs the author's input.