Hook12aaa Using the Craftsmanship Test
Core principle
Comments are a last resort. If naming, decomposition, or types can say it, the code should. A comment must earn its place by saying something the code cannot say.
Iron law
No comment ships without a CRAFT GATE: KEEP verdict.
A comment is STRIP by default. The burden of justification is on the comment, not on its absence.
When the gate fires
When the PreToolUse hook fires on Edit, Write, or MultiEdit of a source-code file in a CODE_PROJECT, invoke craftsmanship-test:craft-gate via the Skill tool. Emit one verdict per new or modified comment, on its own line:
CRAFT GATE: KEEPCRAFT GATE: STRIP — <rule number>CRAFT GATE: REWRITE — <replacement comment text>
Apply the verdict to the diff before the tool call completes.
The eight rules in summary
STRIP: paraphrase, language basics, section dividers, scope-end labels, commented-out code. KEEP: public-API contracts, real why (non-obvious constraint, workaround, surprising business rule). REWRITE: partially why but mostly what — trim to the why-only part.
The full skill at skills/craft-gate/SKILL.md is the source of truth for the rules.