express-intent-in-code
Installation
SKILL.md
- Treat every comment, boolean, nullable return, boolean argument, and inline judgment in the supplied code as a candidate for expressing its intent in code, and decide each in this order: delete it when the code already says the same thing; move it into the code by renaming, choosing a result type, introducing a sum type or named constant, extracting a function, or adding an assertion or test, then delete it; keep it only when it states something the code cannot express, such as an external specification, a workaround for a defect elsewhere, or a deliberate trade-off chosen against the obvious alternative; a comment that ties this code to another place it must stay consistent with is such a constraint until the tie becomes a shared symbol or a test, so move it into a test or keep it. Before keeping a comment, try a name that states the property it describes or a type alias that states its unit, and delete the comment when the name or alias says all of it. An existing comment that cites a source outside the code (a specification section, an incident, a contract clause, another system's behavior) keeps one line at the site even when a test also pins the behavior, because the test pins what happens, not where the rule comes from. A new test holds the intent of a comment you delete or of a constraint the request reveals; a kept comment already carries its reason and gets no companion test, and a guarantee that the language, a library, the runtime, or a type already provides stays with its provider. Keeping applies to comments already in the supplied code; a constraint that the request or the edit reveals follows the rule below on adding comments.
- Apply the same order to unclear names and responsibilities even where no comment exists: perform the smallest restructuring and renaming that makes the intent readable from the code; do not stop at suggesting names or structure. A name is clear when its words literally state what it refers to, so a reader new to the codebase knows the thing from the name alone, before reading its uses or any glossary; hold every identifier and test name, existing or added, to this, and restate an idiom, a metaphor, or industry or team jargon in literal words, judging each word by its ordinary meaning on its own, and rename the identifier even when the literal values it holds or returns are observable output that must stay unchanged. Leave names that are already clear unchanged.
- Limit edits to authorized code and corresponding verification files. A request that says which files may be edited authorizes those files; a request that only names the code to clean up also authorizes every reference in the working tree to a name, type, or signature you change, exported ones included: update those callers, tests, and test names in the same change.
- Before changing how a result, a state, an argument, or an "already done" value is typed, or replacing a
throw, read references/types.md and apply its rules. - Extract a judgment out of a function that performs I/O (awaits a store or request, reads a clock or random source) into a pure function or predicate only when the extraction deletes something that exists now: a fake, layer, or injected dependency an existing test needs; a second copy of the same judgment; or a clock or random read inside the function. A test that a new function could gain, or a name a one-line condition could carry, does not count when the existing tests already cover the judgment through a trivial stub. When nothing is deleted, leave the lines where they are, even a one-line predicate; a comment that explained such a condition moves into a test name or assertion, not into a new function; and report the candidate with what would have had to disappear. Keep I/O order that carries business meaning, such as a re-check inside a transaction, in the calling code. Inside code that is already pure, a helper whose name carries what a comment said is a valid move and needs no deletion test.
- When a repository rule, ADR, or house idiom conflicts with one of these moves, the repository wins: leave the move unapplied and report the conflict.
- Do not add comments during the cleanup, including for a constraint that the request or the edit reveals and no existing comment states: pin it with a test whose name states the reason or with an assertion, and if neither can hold it, report it instead of writing it.
- Preserve supplied inputs, outputs, and externally observed behavior. Keep feature and policy changes outside this cleanup, including changes a comment or TODO asks for, and leave any restructuring that requires an unauthorized target unapplied.
- After the edits, run the configured lint and type check, reporting any the repository lacks, and the supplied behavior checks, including every identified boundary case, and compare observed outputs with the pre-change evidence.
- Remove a lint suppression only when the fresh lint result proves it unnecessary; a suppression that remains keeps the one-line reason the code still does not express.
- Report the verified diff, each kept comment with the reason the code cannot express it, each extraction or brand left unapplied with the reason, lint and behavior-check results, out-of-scope restructuring, failed or unverified writes, and any behavior that remains unverified.