The Craft Gate
The Iron Law
NO COMMENT SHIPS WITHOUT A KEEP VERDICT.
A comment is presumed STRIP until it earns KEEP. The burden of justification is on the comment, not on its absence.
The Rules (apply silently to each comment)
STRIP if the comment paraphrases the code. If the next 1–3 lines of code can be summarized using the identifier names alone, the comment is restating the code. (Beck — "reveals intention" — the code itself should reveal intention.)
STRIP if the comment teaches a language or library basic. "this is a list comprehension", "requests.get sends an HTTP GET", "create empty dict". The reader is a developer, not a student.
STRIP if the comment is a section divider inside a function. # --- validation ---, // === main logic ===, ############. The function is doing too much. Extract a function whose name is the divider. (Fowler — "the comment becomes the new function name.")
STRIP if the comment is a scope-end label. } // end if, # end for loop, } // class Foo. The scope is too long. Refactor to make the close obvious.
STRIP if the comment is commented-out code. Git is the archive. (Martin — "Others won't have the courage to delete it.")
KEEP if the comment is a public-API contract docstring. Docstrings on exported/public symbols that document params, returns, raises, thread-safety, or invariants the caller cannot infer from the signature. (Ousterhout — "if there are no comments accompanying the interface, there is no abstraction.")
KEEP if the comment is a real "why." A non-obvious constraint, hidden invariant, workaround for a specific bug/CVE/upstream quirk, performance trick that looks wrong, or surprising business rule. The "why" must be something the reader cannot derive from the code or function name.
REWRITE if the comment is partially "why" but mostly "what." Trim to the why-only part. If no why remains, the verdict is STRIP.
Rationalization Table
| You think... |
Reality |
| "It clarifies intent." |
The code should clarify intent. STRIP. |
| "Future readers will thank me." |
Future readers read code, not prose. STRIP. |
| "It explains what this function does." |
The function name should. Rename, then STRIP. |
| "It's helpful context." |
Context that isn't a why is paraphrase. STRIP. |
| "It's just a one-liner." |
One-liners accumulate into noise. STRIP. |
| "I'll improve it later." |
Comments rot. Later never comes. STRIP now. |
| "It's standard practice in this team." |
Standard practice is the rot you inherited. STRIP. |
| "Removing it will lose information." |
If the information matters, it belongs in the code or in a real why-comment. REWRITE or STRIP. |
| "But the LLM said this comment is helpful." |
The LLM is the comment-rot machine. STRIP. |
Red Flags (comment-text smells)
- "This function..." / "This method..." / "This class..."
- "Now we..." / "Then we..." / "First we..."
- "Step 1:" / "Step 2:" / numbered narration
- "Returns the result of..." / "Loops through..." / "Iterates over..."
- "Increment..." / "Decrement..." / "Set..." / "Initialize..."
- "Helper function for..."
- Banner ASCII (
#######, =====, -----)
- Closing-brace labels (
} // end)
Not / Yes
Not: # increment counter by 1
counter += 1
Not: # this is a list comprehension
squared = [x*x for x in nums]
Not: // === Validation ===
if (!email.includes('@')) throw new Error('bad email');
Yes: # server timestamps lag 1s on Tuesdays after the 2024-11 NTP
# rollover; subtract before comparing
normalized = ts - 1 if ts.weekday() == 1 and ts > NTP_ROLLOVER else ts
Yes: """Charge a customer.
Raises ChargeFailed on declined cards. Idempotent on retry within
30s via the Stripe-Idempotency-Key header.
"""
Output Protocol
For each new or modified comment in the diff, emit exactly one line:
CRAFT GATE: KEEP — the comment earns its place
CRAFT GATE: STRIP — <which rule> — delete it
CRAFT GATE: REWRITE — <suggested replacement> — replace it
No prose answers. No verdict without applying the rules. No comment ships without KEEP.
After emitting verdicts, revise the Edit/Write to reflect them before the tool call completes.
1---2name: craft-gate3description: Use when about to write or edit a comment in code — evaluates each new or modified comment against the craftsmanship rules and returns KEEP / STRIP / REWRITE per comment. Fires upstream of the comment landing in the file.4---56# The Craft Gate78<HARD-GATE>9Do NOT ship a comment without a KEEP verdict from this gate. STRIP means delete the comment. REWRITE means replace it with a real "why:" reason. Never rationalize a STRIP into a KEEP.10</HARD-GATE>1112<HARD-GATE>13Do NOT think the rules in prose. Apply them silently and emit only the one-line verdict per comment. STOP if you catch yourself drafting prose answers.14</HARD-GATE>1516<HARD-GATE>17**Violating the letter of these rules is violating the spirit of these rules.** "It clarifies intent" is not a why. "Future readers will need this" is not a why.18</HARD-GATE>1920## The Iron Law2122**NO COMMENT SHIPS WITHOUT A KEEP VERDICT.**2324A comment is presumed STRIP until it earns KEEP. The burden of justification is on the comment, not on its absence.2526## The Rules (apply silently to each comment)27281. **STRIP if the comment paraphrases the code.** If the next 1–3 lines of code can be summarized using the identifier names alone, the comment is restating the code. *(Beck — "reveals intention" — the code itself should reveal intention.)*29302. **STRIP if the comment teaches a language or library basic.** "this is a list comprehension", "requests.get sends an HTTP GET", "create empty dict". The reader is a developer, not a student.31323. **STRIP if the comment is a section divider inside a function.** `# --- validation ---`, `// === main logic ===`, `############`. The function is doing too much. Extract a function whose name is the divider. *(Fowler — "the comment becomes the new function name.")*33344. **STRIP if the comment is a scope-end label.** `} // end if`, `# end for loop`, `} // class Foo`. The scope is too long. Refactor to make the close obvious.35365. **STRIP if the comment is commented-out code.** Git is the archive. *(Martin — "Others won't have the courage to delete it.")*37386. **KEEP if the comment is a public-API contract docstring.** Docstrings on exported/public symbols that document params, returns, raises, thread-safety, or invariants the caller cannot infer from the signature. *(Ousterhout — "if there are no comments accompanying the interface, there is no abstraction.")*39407. **KEEP if the comment is a real "why."** A non-obvious constraint, hidden invariant, workaround for a specific bug/CVE/upstream quirk, performance trick that looks wrong, or surprising business rule. The "why" must be something the reader cannot derive from the code or function name.41428. **REWRITE if the comment is partially "why" but mostly "what."** Trim to the why-only part. If no why remains, the verdict is STRIP.4344## Rationalization Table4546| You think... | Reality |47|---|---|48| "It clarifies intent." | The code should clarify intent. STRIP. |49| "Future readers will thank me." | Future readers read code, not prose. STRIP. |50| "It explains what this function does." | The function name should. Rename, then STRIP. |51| "It's helpful context." | Context that isn't a why is paraphrase. STRIP. |52| "It's just a one-liner." | One-liners accumulate into noise. STRIP. |53| "I'll improve it later." | Comments rot. Later never comes. STRIP now. |54| "It's standard practice in this team." | Standard practice is the rot you inherited. STRIP. |55| "Removing it will lose information." | If the information matters, it belongs in the code or in a real why-comment. REWRITE or STRIP. |56| "But the LLM said this comment is helpful." | The LLM is the comment-rot machine. STRIP. |5758## Red Flags (comment-text smells)5960- "This function..." / "This method..." / "This class..."61- "Now we..." / "Then we..." / "First we..."62- "Step 1:" / "Step 2:" / numbered narration63- "Returns the result of..." / "Loops through..." / "Iterates over..."64- "Increment..." / "Decrement..." / "Set..." / "Initialize..."65- "Helper function for..."66- Banner ASCII (`#######`, `=====`, `-----`)67- Closing-brace labels (`} // end`)6869## Not / Yes7071```72Not: # increment counter by 173 counter += 17475Not: # this is a list comprehension76 squared = [x*x for x in nums]7778Not: // === Validation ===79 if (!email.includes('@')) throw new Error('bad email');8081Yes: # server timestamps lag 1s on Tuesdays after the 2024-11 NTP82 # rollover; subtract before comparing83 normalized = ts - 1 if ts.weekday() == 1 and ts > NTP_ROLLOVER else ts8485Yes: """Charge a customer.8687 Raises ChargeFailed on declined cards. Idempotent on retry within88 30s via the Stripe-Idempotency-Key header.89 """90```9192## Output Protocol9394For each new or modified comment in the diff, emit exactly one line:9596`CRAFT GATE: KEEP` — the comment earns its place97`CRAFT GATE: STRIP — <which rule>` — delete it98`CRAFT GATE: REWRITE — <suggested replacement>` — replace it99100No prose answers. No verdict without applying the rules. No comment ships without KEEP.101102After emitting verdicts, revise the Edit/Write to reflect them before the tool call completes.
Hook12aaa