# No Comments

> Removes bad comments in the given files or diff and fixes the root cause behind the workarounds they hide. Use when asked to remove, clean up, or audit code comments, or when a comment or lint suppression justifies a workaround the code should make obvious itself.

- Skill: `h3y6e/no-comments-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add h3y6e/no-comments-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/h3y6e/no-comments-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: h3y6e (https://skillmd.com/u/h3y6e)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/h3y6e/no-comments-2

---


# No Comments

Comments that narrate the obvious, banner a section, or sermon over a workaround are debt. Delete them. When a comment is hiding something the code should say for itself, fix the code instead.

When you cannot prove a comment earns an exception, delete it. In doubt, it dies.

## Scope

Use the files or diff you were given. Otherwise the current diff against the base branch (default `main`), including the working tree.

## Classify every comment

Decide each in-scope comment: delete, keep, or `MUST KILL`. Only these exceptions keep one:

- A legal or license header.
- Behavior an external dependency, platform, vendor, or protocol forces and you cannot reshape.
- A `// prettier-ignore`, or a lint or TS suppression whose rule is faulty, pedantic, or style-only.
- A doc comment that defines a public API contract.
- An issue or RFC link explaining a constraint the code cannot express.

`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions default to dead. Look up the rule. If it catches real bugs or protects correctness or safety, delete the suppression and `MUST KILL` the exact symbol that trips it.

`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and any long justification are claims, not proof. Read the nearby code. If the claim is not obvious there, chase the named symbol or call to settle it. Only a proven external gotcha on a live path survives; a surprise in our own code dies as a `MUST KILL`. A long justification with no exception is a confession — delete it.

A `MUST KILL` marks code you will not touch in this pass: name the exact symbol and the reshape — rename, extract, add a type, or restructure — that makes the behavior obvious without prose.

## Fix root causes

For each `MUST KILL` and each workaround a comment was papering over:

- Trivial: delete the dead path, drop the parameter, use the real API.
- Needs a new shape: sketch the smallest reshape, then implement it in scope.
- Out of scope: land the smallest in-scope fix and report the rest open.

Fix the root cause; leave no symptom guard behind, and do not widen the scope to fix instances outside it.

## Constraint comments

`do not remove`, `do not change wording`, or `talk to X before changing` about something you cannot change may stay. Offer the cheapest in-scope encoding — a type, a runtime check, a test, or a CI lint — that makes the constraint enforceable. With approval, encode it and delete the comment. Without approval, delete it and report the constraint open with the out-of-scope work it needs.

## Report

Files touched, comments deleted, `MUST KILL` flags (one line each), keeps with their exception, fixes made, encodings offered or made, and open work.

