dotfiles/skills/rewrite-comments/SKILL.md

name, description

name	description
rewrite-comments	Inspect and rewrite unclear source-code comments after tracing the surrounding behavior and contracts. Use when asked to review, improve, clean up, or rewrite comments selected by a Git commit, the current working tree, or a named function or method; function requests may target comments on the declaration, inside its body, or both.

Rewrite Comments

Rewrite comments only after understanding the code well enough to preserve its meaning. Make edits in the current working tree; never rewrite Git history unless explicitly requested.

Resolve the target

Determine the scope from the request:

• Commit: Inspect the commit diff and the complete current versions of the code regions it changes. Treat comments added or modified by the commit, plus comments attached to or inside changed declarations, as candidates. If the relevant code no longer exists in the current tree, report that instead of editing an older revision or history.
• Working tree: Inspect staged, unstaged, and untracked changes. Treat comments in or attached to changed declarations as candidates, prioritizing comments changed in the diff.
• Function: Locate the named function or method. Include comments documenting the declaration and comments within its body by default. Honor on, above, or documentation as declaration-only, and within, inside, or body as body-only.

Use repository-aware search and language structure where available. Account for overloads, methods with the same name, generated code, and renamed files. Ask for clarification only when multiple plausible targets remain and choosing one would materially change the edits.

Do not broaden the edit scope merely because nearby comments could also be improved. Read outside the scope freely to establish context.

Build context before editing

Read the full enclosing declaration and enough neighboring code to understand it. Trace relevant definitions and call sites until the important behavior is supported by evidence. Establish, as applicable:

• why the code exists and which callers depend on it;
• accepted inputs, returned values, mutations, side effects, and failure behavior;
• ordering, lifecycle, concurrency, caching, security, and performance constraints;
• invariants, edge cases, compatibility requirements, and intentionally surprising choices;
• types, tests, interfaces, domain documentation, and architectural decisions that define the contract.

Prefer direct evidence from code, tests, and repository documentation. Do not invent intent. If a comment makes a claim that cannot be verified, either make it narrower and factual or remove it.

Stop exploring when the comment's purpose and every retained behavioral claim can be explained from evidence. Avoid tracing unrelated parts of the system.

Judge each candidate

Keep an accurate comment when it already adds durable information. Rewrite or remove a comment when it is unclear, redundant, misleading, stale, speculative, or coupled to incidental implementation details.

Prioritize comments that capture:

• hidden contracts and invariants;
• non-obvious reasons and tradeoffs;
• caller-visible edge cases or failure behavior;
• constraints imposed by another subsystem, API, format, or compatibility promise;
• deliberate deviations from the obvious implementation.

Avoid comments that:

• narrate syntax or restate names and types;
• describe mechanics that are immediately apparent from the next few lines;
• duplicate the type system or stable API shape without adding a contract;
• predict future work without an actionable, repository-standard marker;
• mention transient details, line positions, counts, or internal steps likely to drift;
• preserve a confident explanation unsupported by the code.

Retain required legal notices, tool directives, generated-file markers, suppression comments, and structured documentation tags unless the task explicitly includes them and changing them is safe.

Rewrite

Edit only comments unless the user explicitly requests code changes. Preserve behavior, public API, formatting conventions, comment style, and documentation syntax.

Write concise, direct comments at the narrowest useful location. Explain why, must, unless, or despite when those ideas matter. State contracts in terms of observable behavior rather than current implementation. Include inputs and outputs only when their semantics, ownership, units, normalization, sentinel values, or failure modes are not already obvious from code and types.

Delete a comment when removal is clearer than a rewrite. Do not add comments merely to replace every removed one, and do not churn wording without a meaningful clarity or correctness improvement.

Verify and report

Review the final diff and confirm that edits are limited to the resolved scope and do not alter executable code. Re-read each edited comment against its code and callers. Run repository-required checks for changed files and any broader checks explicitly required by repository instructions; treat failures as blocking.

Summarize which comments changed and the hidden behavior or contract they now clarify. Mention comments intentionally removed, unresolved ambiguity, unverifiable claims, and checks that could not be run.