# shut-up-and-code

Adopt this skill: https://proskills.md/skills/other/chl03ks-shut-up-and-code-skills-shut-up-and-code

Page: https://proskills.md/skills/other/chl03ks-shut-up-and-code-skills-shut-up-and-code
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/shut-up-and-code/SKILL.md
size: 6343
upstream: https://github.com/chl03ks/shut-up-and-code/blob/main/skills/shut-up-and-code/SKILL.md

```text
---
name: shut-up-and-code
description: Load-bearing comments only. Use when writing or editing code in any language, or when the user asks about comment standards.
---

# shut-up-and-code

A comment earns its place by being **load-bearing**: delete it and a competent reader loses something the code cannot tell them. Write those. Let the code speak for everything else.

This holds for every file you write or edit for the rest of the session, and does not lapse when the topic changes. If you are unsure whether it still applies, it does. The user turns it off by saying "normal comments" — confirm in one line, then return to your default style.

## The test

Before writing a comment, name what the reader loses without it. A concrete answer means it is load-bearing, so write it. Silence — or an answer that restates the line below — means the code already carries it, so let the code carry it.

Say it in different words than the code. A comment assembled from the identifiers beneath it is that line spelled twice. If the only phrasing you have reuses the names already on screen, there was nothing to add.

The test runs per clause, not per comment. A sentence can smuggle restatement inside itself — a load-bearing fact up front, a "…so we must" tail respelling the code below it. Keep the clause that carries the answer; every further clause needs its own. A four-line comment with one load-bearing line is one line long.

Comments describe the code as it stands, in the voice of the file. The edit that produced them belongs in the commit message.

Apply the same test to comments already in code you touch: load-bearing ones stay as they are, and one your own edit made false gets corrected or removed in that same edit. An edit can falsify a comment it never touched — reread the comments around the edit site, not only the ones you rewrote.

## What is load-bearing

Five kinds, in practice:

1. **Why, not what** — a decision, tradeoff, or constraint the code cannot express. `// Retry 3x — the upstream 502s on cold start.`
2. **A landmine** — something that looks safe to change and is not. `// Set the auth header before reading the body.`
3. **A deliberate omission** — something absent on purpose that a reader would otherwise take for a bug. `// Unsorted; the caller re-sorts by locale.`
4. **A pointer out of the file** — a ticket, RFC, spec section, or upstream bug that explains the code's *shape*. The bar: a reader who follows it learns why the code could not be simpler. A ticket number stamped on a change because a ticket existed is filing, and `git blame` already files it.
5. **A toolchain annotation** — `// eslint-disable-next-line`, `# type: ignore`, pragmas, codegen markers.

And what fails, in the same practice:

- `// Increment the counter` above `count++` — the line, spelled twice.
- `// Using a Map for O(1) lookups` — the data structure announcing itself.
- `// PREF-2841: fix rate limiter` — filing, not shape.
- `// Handles a single webhook delivery` on `handleWebhookDelivery` — the signature in prose.
- `// Stripe retried and we double-charged 14 customers on 2026-08-04` — incident history. It belongs in the postmortem the ticket links to; the code needs only the constraint that survived it.

Density follows the file. An uncommented neighbourhood stays uncommented. A heavily commented one sets its ceiling by its load-bearing comments, not by its total.

## Contracts

Everything above governs comments *inside* a function. The comment *on* it is a different instrument — and it is not owed to every function that happens to be exported.

A **contract** exists so callers never read the body. Write one when the signature leaves a question a caller must answer to call correctly:

- **Units and bounds** — `timeout` in what? Is `end` inclusive?
- **Failure** — what it returns, raises, or panics on, and when.
- **Caller obligations** — preconditions, call ordering, ownership, whatever an `unsafe` block trusts.
- **Concurrency** — safe to call from more than one thread, or not.
- **The edges** — empty, zero, negative, overflow: the cases you had to decide.

Name the question before you write. If you cannot name one, the signature is already the contract — write nothing. `export` is not the trigger; an unanswered question is.

Then answer it and stop. A sentence that re-spells the function's name in prose — "Handles a single webhook delivery", "Stores the session" — is the whole signature restated, and it fails on the same grounds as `// increment the counter`. Open on the answer, in the form the language expects.

Where a project's own standard overrides this skill, the project wins. Internal helpers carry no contract; they get the ordinary test.

## Reach for the alternative first

Most explanations land better somewhere other than a comment:

- Rename the variable or function until it says what the comment would have said.
- Extract the confusing block into a named function.
- Write a test that demonstrates the behaviour.
- Put the reasoning in the commit message or PR description.
- Put it in your response to the user. Chat prose is free, and this ruleset governs files, not replies.

## When the comment is hard to write

Difficulty explaining a block is a fact about the code, not about your prose. Split the function, name the intermediate value, or fix the abstraction — then the comment either writes itself or turns out to be unnecessary. A block that needs a paragraph was asking to be two functions.

## The audit point

A commit — or the end of any turn that edited files — is where the audit runs, unprompted. Account for **every comment in the diff, contracts included**: for each one, state what the reader loses without it, clause by clause. Keep the ones with a concrete answer, drop the rest, then rewrite each survivor to the shortest phrasing that still carries its answer — the examples above are the target length.

Then search the file for every identifier your edit renamed or deleted. A comment still naming one is now false, and a false comment is worse than none.

Test names are comments the runner prints: a `describe` or `it` string claims only what its body exercises.

The diff is ready when every surviving clause has an answer, and none can be shorter without losing it.
```

## File: README.md
upstream: https://github.com/chl03ks/shut-up-and-code/blob/main/README.md

````text
# shut-up-and-code

**Load-bearing comments only.** A Claude Code plugin that stops the agent narrating your code back to you.

Claude comments reflexively. Most of what it writes restates the line below it — or, on anything exported, swells into a doc block that restates the signature and pastes in whatever context it was handed. A rule in `CLAUDE.md` doesn't reliably stop either. This ships that rule as a skill instead — as something Claude can load on its own, or that gets injected at the top of every session.

## The difference

Before:

```ts
// Function to calculate the total price
function calculateTotal(items: Item[], taxRate: number): number {
  // Initialize the sum
  let sum = 0;
  // Loop through all the items
  for (const item of items) {
    // Add the item price to the sum
    sum += item.price;
  }
  // Apply the tax rate and return
  return sum * (1 + taxRate);
}
```

After:

```ts
function calculateTotal(items: Item[], taxRate: number): number {
  let sum = 0;
  for (const item of items) {
    sum += item.price;
  }
  return sum * (1 + taxRate);
}
```

Nothing was lost. That's the point.

The same test applies to doc comments, which is where the bulk usually hides. Hand Claude an incident, a ticket and an RFC as background, and all three end up above the function:

Before:

```ts
/**
 * Handles a single Stripe webhook delivery.
 *
 * Resolves with 200 for every event it accepts, dedupes, or discards: Stripe
 * redelivers on any non-2xx or on no reply within 10 seconds, and a redelivery
 * is what charged 14 customers twice (PREF-3102, docs/rfc/047-webhook-idempotency.md).
 *
 * Effects run at most once per `event.id`, enforced by the unique constraint on
 * `processed_events.event_id` rather than by a prior read, so concurrent
 * deliveries of the same event cannot both proceed.
 *
 * Events older than 72 hours are discarded unprocessed and still answered 200.
 *
 * Rejects only when the database is unreachable, which is the one case that
 * should reach the caller as a 5xx and earn a Stripe retry.
 */
export async function handleStripeWebhook(event: Stripe.Event): Promise<Response>
```

After:

```ts
/**
 * Always 200; duplicates and events older than 72h are dropped silently — any
 * other status makes Stripe redeliver. See docs/rfc/047-webhook-idempotency.md.
 */
export async function handleStripeWebhook(event: Stripe.Event): Promise<Response>
```

The incident stayed in the postmortem. What reached the file is the constraint that outlived it.

## Install

```bash
claude
```

Then, in the session:

```
/plugin marketplace add chl03ks/shut-up-and-code
/plugin install shut-up-and-code@shut-up-and-code
```

## Two ways to use it

**1. Call it.** Type the skill name in any session:

```
/shut-up-and-code
```

It applies from there until the session ends. Claude will also reach for it on its own when it's about to write code.

**2. Always-on.** Create the flag file once, and the ruleset is injected at the start of every session — on startup, resume, clear, and compact:

```bash
touch ~/.claude/.shut-up-and-code-always
```

You'll know it's live because the session opens with:

```
SHUT UP AND CODE ACTIVE (always-on).
```

## Turning it off

| Scope | How |
| --- | --- |
| This session | Say `normal comments` |
| Always-on, permanently | `rm ~/.claude/.shut-up-and-code-always` |
| Uninstall | `/plugin uninstall shut-up-and-code@shut-up-and-code` |

## What it actually enforces

The default is no comment. A comment ships only if it's **load-bearing** — delete it, and a competent reader loses something the code cannot tell them. In practice, five kinds survive:

1. **Why, not what** — a decision, tradeoff, or constraint the code can't express. `// Retry 3x — the upstream 502s on cold start.`
2. **A landmine** — something that looks safe to change and isn't. `// Set the auth header before reading the body.`
3. **A deliberate omission** — something absent on purpose a reader would take for a bug. `// Unsorted; the caller re-sorts by locale.`
4. **A pointer out of the file** — a ticket, RFC, or upstream bug that explains the code's *shape*. A ticket number stamped on a change because a ticket existed is filing, and `git blame` already files it.
5. **A toolchain annotation** — `// eslint-disable-next-line`, `# type: ignore`, pragmas, codegen markers.

Doc comments get a narrower rule than "public means documented." A contract is written when the signature leaves a question the caller must answer to call correctly — units, failure modes, call ordering, thread safety, edge cases. `export` alone is not the trigger, and a contract that re-spells the function's name in prose fails on the same grounds as `// increment the counter`.

It also redirects the urge elsewhere: rename the variable, extract the function, write the test, put it in the commit message, or just say it in the chat reply. And it leaves comments in code you're only passing through alone — the rule governs what Claude writes, not a licence to strip your codebase.

Full ruleset: [`skills/shut-up-and-code/SKILL.md`](skills/shut-up-and-code/SKILL.md).

## Does it work?

Measured — because the first version didn't.

Two scenarios, run against fresh Claude Code subagents with no shared context: a routine edit on an existing file with a Linear ticket in the prompt, and a webhook handler written from a pile of incident background. The metric is comment lines as a share of file lines. Three conditions: the skill loaded, no skill at all, and the current version.

**Scenario A — routine edit**

| Condition | Comment share of file, one column per run |
| --- | --- |
| No skill | 5%, 7%, 7%, 7% |
| v0.4.0 | 30%, 33%, 36%, 38% |
| **v0.5.0** | **7%, 9%, 9%, 13%** |

v0.4.0 produced **roughly five times the comment volume of loading no skill at all**, and never once landed inside the no-skill range. The cause was its own Contracts section: it made a doc comment mandatory on anything exported, said in as many words that the comment did its job "even when it restates the signature in prose", and then exempted the category from the audit that would have cut it. Two exported functions bought nineteen lines of JSDoc.

**Scenario B — handler written from incident context** (an outage, a ticket ID, an RFC path, a finance deadline, and "I'm handing this off next week")

| Condition | Lines | Comment lines | Share | Context terms pasted into the file |
| --- | --- | --- | --- | --- |
| No skill | 66 | 26 | 39% | 5 |
| v0.4.0 | 54 | 19 | 35% | 4 |
| **v0.5.0** | **40, 46** | **10, 12** | 25%, 26% | **1, 1** |

Read the comment-line column, not the share: v0.5.0 writes a much shorter file, so the percentage holds roughly flat while the absolute volume more than halves.

The leak count is the result that matters. The one surviving term is the RFC path — a pointer a reader can follow. Gone: the ticket ID, the date, "charged 14 customers twice". The two facts that constrain the code, Stripe's 10-second redelivery and finance's 72-hour window, are still there. The constraint outlived the incident; the incident didn't.

Four to six runs per arm — small, and the exact percentages aren't precise to the point. Fixtures, prompts, every raw output file and the measuring script are in [`benchmark/`](benchmark/), including [one rule that was cut for failing it](benchmark/README.md#what-this-does-not-show).

## Why a skill and not a CLAUDE.md line

Verbose commenting is the model's default, and defaults beat instructions. People report `CLAUDE.md` rules, memory entries, and hooks all failing to suppress it ([claude-code#65961](https://github.com/anthropics/claude-code/issues/65961)). A skill lands as a loaded document at a point where the model is deciding how to write, which holds better than a line competing for attention with the rest of your config.

If you want the root-cause fix as well, some report that Opus gets a shorter system prompt than Sonnet, with the anti-verbosity rules trimmed out. Forcing the long 
````
