# Prune Comments

> Zero-tolerance comment eradication and structural refactoring. Enforces a strict "code speaks for itself" paradigm. Deletes ALL inline comments. If a comment explains complex logic, a platform quirk, or a constraint, you MUST refactor the code (extract methods, add runtime assertions, use custom exception messages, or rename types) to make that reality executable or structurally obvious. Takes an optional argument scoping the pass: a file or directory path, a PR number/URL, a branch name, or "full repo"/"repo".

- Skill: `austek/prune-comments` (Agent Skill)
- Install (CLI): `npx skillmds@latest add austek/prune-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/austek/prune-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: austek (https://skillmd.com/u/austek)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/austek/prune-comments

---


# Prune Comments (Strict Zero-Tolerance)

Reviews every existing non-doc comment and deletes or refactors it. The codebase must
adhere strictly to clean code principles where executable architecture replaces narration.

## Scope

Resolve `$ARGUMENTS` to a target in this order — stop at the first match:

1. **No argument** → run `git status --porcelain`. Scope to uncommitted changes.
2. **A filesystem path** → scope to that path.
3. **A PR reference** → scope to files in that PR's branch.
4. **A branch name** → diff against merge base with `origin/HEAD` and scope to touched files.
5. **Whole-repo request** → the entire repo is in scope.

Regardless of scope, skip: `.git`, build/output dirs (`target`, `dist`), and vendored/generated code.

## The Bar: Total Deletion & Executable Refactoring

**ALL inline comments (`//`, `#`, `--`) fail the bar and MUST be deleted.**

Instead of leaving comments, you must apply these transformations:

* **Restatements & Design Defenses:** Delete silently. Identifier names are the documentation.
* **Commented-out code:** Delete silently. Git history holds it.
* **Complex Logic:** You MUST refactor the code (extract methods, rename variables, simplify branching) to make the intent obvious.
* **Platform Quirks / Safety Constraints / Cross-file Facts:** You MUST encode these into the architecture. Translate the warning into a runtime assertion (`assert`, `require`), a highly descriptive custom exception message, or a dedicated, explicitly named wrapper method that isolates the quirk.

## What never gets touched

- License/copyright headers.
- `SAFETY:` / `# Safety` comments strictly required above `unsafe` blocks.
- Formal doc comments (`///`, `/** */`, docstrings) — these define API contracts and are out of scope.

## Process

1. Resolve scope from `$ARGUMENTS`.
2. For each file in scope, find every inline comment.
3. Edit in place: **Delete all inline comments.** Refactor code, extract methods, or add descriptive exception/assertion messages to absorb any critical constraints previously hidden in the comments. Do not add any new comments.
4. After editing a file, verify it still parses/compiles/lints cheaply.
5. Re-scan to ensure absolutely zero inline non-doc comments remain.

## Reporting

Summarize per file: lines of comments eradicated, and list every structural refactor (method extractions, assertions added, exceptions renamed) performed to absorb load-bearing rationale.