imMamdouhaboammar/anti-slop-engineering / .openclaw/skills/comment-budget-guard
comment-budget-guard
VerifiedEnforce CCR <= 0.35 and eliminate obvious syntax play-by-play comments.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.0 KB |
SKILL.md
View on GitHub---
name: comment-budget-guard
description: "Enforce CCR <= 0.35 and eliminate obvious syntax play-by-play comments."
homepage: https://github.com/imMamdouhaboammar/anti-slop-engineering
license: MIT
---
# Comment Budget & Obviousness Guard
> Enforce the Zero-Obviousness & Anti-Truism Doctrine by bounding Comment-to-Code Ratios (CCR) and eliminating syntax play-by-play comments without penalizing docstrings or safety invariants.
## Why This Skill Is Needed & Target State
AI code generators suffer from pervasive comment slop: narrating obvious syntax line-by-line (`// increment counter`, `// return result`, `// check if null`). Naive counters (e.g. `max-added-comments: 10`) break on large, well-documented pull requests while letting micro-PRs with 9 trivial comments slip through.
The target state is a metric-driven Comment-to-Code Ratio (CCR) engine that:
1. Calculates $\text{CCR} = \frac{\text{added\_comments}}{\max(1, \text{added\_code})}$.
2. Enforces an activation floor ($\ge 20$ added comments) before ratio warnings trigger.
3. Automatically exempts markdown docs, configuration files, SQL migrations, and SPDX license blocks.
4. Detects and blocks syntax narration slop while strictly safeguarding `// SAFETY:` contracts, `///` Rust doc comments, and `/** ... */` docstrings.
## Invariant Rules
1. **Silence over noise:** If a line of code is obvious to a competent engineer, narrating it with comments is banned.
2. **Contract preservation:** Never strip or discourage `// SAFETY:` proof annotations, formal docstrings, or license headers.
3. **Proportional budget:** High CCR on its own is classified as `review`; it is upgraded to `blocker` only when confirmed syntax play-by-play narration patterns are detected.
## CLI Usage
```bash
# Check git diff against base commit
bunx anti-slop-engineering comment-guard --base HEAD
# Audit unified diff patch file directly with custom threshold
bunx anti-slop-engineering comment-guard \
--diff-file diff.patch \
--threshold 0.35 \
--min-floor 20 \
--json
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |