anti-slopSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: antislop-code
description: "Code comment hygiene for AI coding agents: remove generic AI-slop comments, keep the valuable ones, never touch the code."
allowed-tools: Read Write Edit Glob Grep
---
# antislop-code

> Anti Slop: Rules for AI Coding Agents. Code Comments skill

> Part of the antislop system. Read together with `antislop.md` (the core). This skill filters comments that read as generically AI (decorative, restating the obvious, stiff, loud) while preserving the comments that carry real information. It references core rules by number and never duplicates or renumbers them. Load it when the task writes or edits code comments.

## How to use this skill

- Load together with `antislop.md` whenever the task touches code comments. The core holds the mechanism (the purpose test, the three tiers, the Delivery Gate); this skill holds comment-specific depth.
- Every entry has the same shape: **Tell** (the pattern), **Why** (why it reads as slop), **Fix** (what to do instead), with the governing core rule cited as R-XX.
- **Scope guardrail:** this skill only modifies comments. Never modify executable code, identifiers, imports, formatting, indentation, whitespace, control flow, or logic. When in doubt, leave the code untouched.
- The Delivery Gate in the core remains the gate. The "Code Comment Checklist" at the end of this file is the comment-specific supplement to run alongside it.

## Comments That Add Nothing

### Decorative Separators

- **Tell:** banner comments built from repeated characters, ALL CAPS labels, or box drawing around a section name: `// =======================` around `Authentication`, `// -------- WORKFLOW --------`, or a `/* ---- ROUTES ---- */` header.
- **Why:** the decoration is the message. A label wrapped in `=` or `-` signals "AI made this" without adding information, and ALL CAPS reads as shouting.
- **Fix:** replace with a single plain line, or remove entirely if the label adds nothing (R-31).

### Restating the Obvious

- **Tell:** a comment that repeats what the next line or declaration already shows, like `// Initialize the variable` above `let count = 0`, `// User class` above `class User {}`, `// Validate user` above `function validateUser()`, or `const userAge = 25; // User age is 25`.
- **Why:** it doubles the reading load without adding anything. The code already says it; the comment just repeats it.
- **Fix:** remove and leave the line of code alone.

### Workflow Narration

- **Tell:** comments that narrate the flow step by step, like `// Step 1: Validate input`, `// Step 2: Process request`, `// Step 3: Return response`, or `// First...`, `// Next...`, `// Finally...`.
- **Why:** the control flow is visible in the code itself. Numbering it reads as a checklist, not an explanation.
- **Fix:** remove. If the flow is genuinely hard to follow, that is a structure problem, not a missing comment problem.

### Empty Labels

- **Tell:** generic labels with no information behind them: `// Main logic`, `// Core logic`, `// Business logic`, `// Helper function`, `// Entry point`, `// Error handling`, or `// Note: This is important.` / `// Important: Please read.`
- **Why:** the label names a category, not a fact. "Main logic" tells the reader nothing they could not infer from the code.
- **Fix:** remove unless the label carries specific information. "Note: retries happen only on 5xx" earns its place; "Note: this is important" does not.

### Vague Placeholders

- **Tell:** comments that promise future work without saying what: `// TODO: Improve this`, `// Future improvements`, `// Additional optimization can be added here`, `// Add more validation`.
- **Why:** a vague TODO is noise. It names a feeling (this could be better) instead of a task (what, and why).
- **Fix:** remove. Keep a TODO only when it names a specific task with enough context to act on.

### Signature Echo

- **Tell:** documentation that only restates the signature, like a JSDoc block that repeats `@param price The price.` and `@returns Total price.` for a function whose name and parameters already say all of it.
- **Why:** docs that echo the signature add length, not understanding. The reader learns nothing new.
- **Fix:** simplify or remove the echo. Keep documentation that explains business rules, edge cases, assumptions, algorithms, limitations, side effects, API behavior, or security implications. Never strip real documentation.

### Decorative Emoji

- **Tell:** emoji used as decoration in comments, like `// ✅ Validation` or `// 🚀 Performance`.
- **Why:** emoji is visual noise in code, and the specific set (✅, 🚀, 🔒) is the AI default vocabulary.
- **Fix:** replace with plain English, or remove if the label adds nothing.

### End Markers

- **Tell:** comments that only mark the end of a block, like `} // end if`, `# End of function`, or `// End processOrder`.
- **Why:** the closing brace already ends the block. The marker exists out of habit, not need.
- **Fix:** remove. In the rare case an end marker genuinely helps a long file, keep it only where it prevents confusion, not as a habit.

## How It Should Read

### The Over-Explained Comment

- **Tell:** one comment that runs on for several lines, stacking reasons, context, and history around a fact that fits in one line: a four-line block explaining that a stub sits on PATH, which release introduced the workaround, and what broke before it. Every sentence is true. The length is the tell.
- **Why:** a person leaves a note, a generator writes a case. Padding a one-line fact into a paragraph, building a "because X, so Y, and therefore Z" chain, or citing the issue number and the version that fixed it are the same flourish as any other AI pattern, and they bury the one line that matters under the ones that do not.
- **Fix:** cut to the constraint alone: one line, two at most, never three. Keep the platform trap, the silent failure, the protocol rule, the performance cost. Drop the issue number, the version history, and the reasoni

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

declared (4 observation(s))

Network

none-observed

Shell

declared (1 observation(s))

Dependencies

not all pinned

Secrets in source

none-found

Findings (1)

@clack/prompts, picocolors

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: anti-slop](https://modelsatlas.com/skills/miqdadbadjuber/anti-slop/badge.svg)](https://modelsatlas.com/skills/miqdadbadjuber/anti-slop/)

Not your listing, or something out of date? Claim or update your listing.