---
name: deslop-comments
description: Rewrite code comments and docs touched during the current conversation into Simple English, stripping AI-slop / AI-lingo vocabulary and negative framing. Use when the user says "deslop these comments", "clean up the comments we just wrote", "rewrite this in plain English", or after a review flags comments as convoluted/AI-sounding. Comment-only - never changes function names, APIs, or behavior.
---

# Deslop comments

Rewrites comments and doc blocks into short, direct Simple English. This is a comment-only pass: no renames, no logic changes, no behavior changes.

## Scope

Default scope is **files the current task actually created or edited** - find the candidate set with `git diff --name-only` / `git status --short` against the base the conversation started from. If the user names specific files, a directory, or a Pull Request instead, use that scope.

Do not expand scope to a file just because the agent `Read` it or reviewed it in passing - a debugging or review session routinely reads many unrelated files, and reading one is not authorization to rewrite its comments. If there is no edited-file set and no explicit scope from the user, ask which files to cover.

## What counts as slop

Rewrite a comment if it has any of:

1. **Dense, multi-clause sentences** that try to explain everything at once instead of one idea per sentence.
2. **Negative / before-state framing** - describing removed code, or leading with "not X" when X was never the point. Keep "not X, it's Y" only for a genuine edge case, a non-obvious gotcha, or bug-fix rationale worth flagging; otherwise state the current behavior directly.
3. **AI buzzwords** in place of plain software engineering vocabulary. Common offenders and their replacements:
   - `gate` / `gates` / `gating` → "check", "decides whether to show...", "authentication check", "feature check"
   - `guard` → "check" / "prevent"
   - `backstop` → "handles the case where..." / "protects us either way"
   - `load-bearing` → "useful"
   - `predicate` → "helper"
   - `presentational` (component) → "this component only displays the result"
   - "flattens to a bare new Error" → "turns into a plain new Error"
   - `harness` → name the concrete thing: "test setup", "test wrapper", "fixture", "mock server", or "runner"
   - `realm` → "environment", "runtime", or "context" (unless it's the precise JS-realm technical term)
   - `landed` → "implemented"
   - `mint` → "created"
   - `leverage` → "use"
   - `utilize` → "use"
   - `surface` → "show" / "return" / "report"
   - `plumb` / `wire` → "pass" / "connect" / "call"
   - `broker` → "handle" / "route" / name the service/helper (keep broker if that's the concept name in some architecture, library, service, etc.)
   - `canonical` → "shared" / "standard"
   - `churn` → "unnecessary changes"
   - `invariant` → "rule" / "condition" / "constraint" / or something like "state that must stay true"

     Do not apply this as a blind blacklist. Keep the original word when it is the precise domain term, especially for security, type-system, React, database, FHIR, or JavaScript runtime concepts. For example, `opaque` is a precise security/API term for an id, token, or string whose structure and meaning a caller must not depend on ("recipient is an opaque viewer-supplied string; never log it"); it is not on the replacement list above, so leave it — "generic" would drop that contract.
4. **Undocumented return shapes.** A function returning an object or union should say what each field/variant means, not just that it "returns a result."
5. **Any other AI-slop or AI-lingo words, framing, structure.**

## What to leave alone

- Function, type, and API names - this is a comment-only pass.
- Log strings and error messages shown to users.
- Generated files (e.g. `*.gen.ts`, Prisma client output).
- Genuine security markers or contracts written as caps-negatives (`NEVER log PHI`, `Does NOT upsert`) - these are useful warnings, not slop.
- User-facing UI copy (JSX text nodes rendered to the browser) - that's product copy, not a code comment.
- Already-clear one-liners that don't exhibit any of the problems above. Don't rewrite for the sake of rewriting.

## Process

1. Build the file list per Scope above.
2. For each file, read every comment/doc block (`//`, `/* */`, `/** */`, `#`, `%`, depending on the language) and check it against "What counts as slop." Skip anything covered by "What to leave alone."
3. Rewrite in place with `Edit`. Prefer one idea per sentence. When a function's return type is a union or object with meaningful fields, spell out what each branch/field means using the comment body or JSDoc (or similar) if it's a project pattern.
4. After editing, confirm the diff is comment-only: `git diff -- <files>` should show no code-line changes, only comment text.
5. Run the project's lint/typecheck on touched files (e.g. `pnpm biome check <files>`, `pnpm --filter <pkg> typecheck`) to confirm nothing broke.
6. Summarize what changed in 1-2 sentences - don't restate every line edited.

## Example

Bad (dense, negative framing, buzzwords):
```
// Server-to-server auth gate. Fail closed if the token is unconfigured.
try {
   if (!verifyServiceAuth(request)) { ... }
}
```

Good (Simple English, positive framing, no AI-lingo structure):
```
// Server-to-server authentication check. Deny the request if the token is unconfigured.
try {
   if (!verifyServiceAuth(request)) { ... }
}
```

Bad:
```
// NOTE: this forward-block is a UI courtesy only, not a per-step gate.
// `currentStepIndex` derives from the current URL path — not from saved
// progress — so navigating to a later step's URL directly bypasses it
// entirely. The template deliberately ships no per-step route guards
// (forks may want different ordering/skipping rules); the integrity
// backstop is the server-side readiness check at intake completion,
// which refuses to finalize while any step is missing.
const canNavigateToStep = useCallback(...)
```

Good:
```
// This limits forward navigation in the UI only. `currentStepIndex` comes from
// the current URL path, not from saved progress, so visiting a later step's URL
// directly still works. The template intentionally ships no per-step route
// checks, since forks may want different ordering or skipping rules. The real
// safeguard is the server-side check at intake completion, which refuses to
// finalize while any step is missing.
const canNavigateToStep = useCallback(...)
```

Bad:
```
// Throttle first — cheapest gate. Bounds Argon2 CPU amplification and
// request flooding on this public endpoint (best-effort, per-instance).
const rate = await checkRateLimit(getClientKey(request))
```

Good:
```
// Check the rate limit first, since it's the cheapest check to run. Bounds
// Argon2 CPU amplification and request flooding on this public endpoint.
const rate = await checkRateLimit(getClientKey(request))
```

Bad:
```
/**
 * Whether the patient may finalize their intake: every required step must be
 * validly filled and one of the payment steps must have a saved response.
 * Server-authoritative — `completeIntake` enforces the same rule, so a client
 * skipping this check cannot complete a partial intake.
 *
 * Required steps are validated (not presence-checked) so a Save-for-later draft
 * counts as still-missing: the patient is sent back to the earliest unfinished
 * step (e.g. Demographics) rather than skipped past it to a later one.
 */
export async function getIntakeReadiness(headers: Headers): Promise<IntakeReadiness> { ... }
```

Good:
```
/**
 * Returns whether the patient can finalize their intake: every required step
 * must pass its schema, and one of the payment steps must have a saved
 * response. `completeIntake` enforces the same rule on the server, so a
 * client cannot complete a partial intake by skipping this check. A
 * Save-for-later draft counts as missing, which sends the patient back to
 * the earliest unfinished step (e.g. Demographics) instead of skipping past
 * it. In the returned object, `ready` tells whether the intake can be
 * completed, and `missingSteps` lists the keys of the steps still missing.
 */
export async function getIntakeReadiness(headers: Headers): Promise<IntakeReadiness> { ... }
```