01
What this skill does
Use this skill when a file needs durable comments around intent, constraints, data meaning, public contracts, or non-obvious control flow. It reads the local comment style first, removes weak or redundant comments where needed, and adds only the comments that help future readers reason about the code.
02
When to use it
- SignalDocumenting exported functions, interfaces, classes, types, and configuration objects.
- SignalReplacing stale or syntax-level comments with explanations that survive implementation churn.
- SignalClarifying fields, options, state variants, and branches whose meaning is part of the contract.
03
How it works
- 01
Read top-level definitions before editing so comments match the file's real ownership boundaries.
- 02
Detect the nearby comment language, tone, density, and formatting conventions.
- 03
Rank comment candidates by reader value, then choose the smallest useful granularity.
- 04
Rewrite or remove low-value comments before adding new ones, preserving one documentation voice.
- 05
Re-read the final file to make sure each comment still holds if small implementation details change.
04
What you get back
- SignalA targeted patch to comments only, unless the user explicitly asks for broader code changes.
- SignalComments that explain why a branch exists, what a field means, or where misuse is likely.
- SignalA concise completion note with any verification that was requested.
05
Important boundaries
- SignalDo not add narration that merely restates syntax.
- SignalDo not stage, commit, or advance Git state unless the current request explicitly asks for it.
- SignalMatch the repository's existing comment style instead of imposing a new documentation system.
06