Skip to content

astroville/sprout / .claude/skills/code-scrub

code-scrub

Verified

Methodology and rules for scrubbing codebases — removing dead code, weak types, duplication, bad comments, defensive programming, and legacy cruft.

FileKindSize
SKILL.mdskill md4.7 KB
---
name: code-scrub
description: Methodology and rules for scrubbing codebases — removing dead code, weak types, duplication, bad comments, defensive programming, and legacy cruft.
compatibility:
  - opencode
  - cursor
  - claude
metadata:
  audience: agents
  purpose: skill-routing
---
# Code Scrub Methodology

## Core principle

Scrubbing improves code quality by **removing waste** — not by adding abstractions. Every change must make the code simpler, not more complex. If a fix introduces more indirection than it removes duplication, don't make it.

## Confidence levels

Categorize every finding:

| Level | Criteria | Action |
|---|---|---|
| **High** | Clearly unused, clearly duplicated, clearly wrong type, clearly misleading comment. Removal/fix has no behavioral change. | Implement immediately |
| **Medium** | Likely an improvement but requires judgment — could affect behavior, might break an edge case, or the "right" fix is debatable. | Document as recommendation, don't implement |
| **Low** | Stylistic, cosmetic, or would require significant restructuring. | Mention in assessment only |

## Rules for each concern

### Deduplication (DRY)
- Only consolidate when the duplicated code is **genuinely the same concern**, not just similar-looking code that happens to share structure
- Don't extract utilities for code that's duplicated only twice — wait for three or more
- Don't create "god util" packages. Place shared code in the package that owns the concept
- If consolidation requires adding parameters or flags to handle variant behavior, it's probably not worth it

### Type strengthening
- `any`/`interface{}` is legitimate for: JSON marshaling, database/sql args, generic containers, protocol boundaries (MCP, GraphQL)
- Replace with concrete types when: the value is always used as one type, or the set of types is small and known
- Don't create wrapper types just to avoid `any` — the cure shouldn't be worse than the disease
- Check that replacement types are actually correct by tracing usage upstream and downstream

### Dead code removal
- Verify with static analysis tools first (`deadcode`, `knip`, tree-shaking analysis)
- Grep for all references before removing exported symbols
- Watch for: reflection, embed directives, interface implementations, build tags, test helpers
- If uncertain, leave it and document

### Dependency structure
- Go: no circular imports possible, focus on coupling and cohesion
- TypeScript/JS: use tools like `madge` to detect cycles
- Don't restructure working dependency graphs for cosmetic reasons
- A "god package" that wires things together (CLI layer, main, app bootstrap) is architecturally correct

### Defensive programming
- Keep error handling for: user input, network I/O, file I/O, external APIs, deserialization
- Remove error handling that: swallows errors silently, returns fallback values that mask bugs, catches panics without logging
- `_ = expr` is fine for: log writes, cache writes, cleanup operations, non-critical side effects
- `_ = expr` is not fine for: data writes the user expects to persist, operations where failure means silent data loss

### Legacy and fallback code
- Backward compatibility for **user-facing config** is legitimate — don't remove it without a migration path
- Backward compatibility for **internal data formats** should be removed if no deployments use the old format
- Comments saying "deprecated" or "legacy" don't automatically mean the code should be removed — check if it's still needed
- Feature flags and conditional paths that only have one active branch should be simplified

### Comments
- Remove: narrating comments ("increment counter"), section dividers that add nothing, AI boilerplate, work-in-progress references
- Keep: comments explaining **why** (not what), non-obvious algorithm explanations, links to specs/tickets, license headers, godoc/JSDoc for public APIs
- Replace (don't just remove): misleading comments that describe behavior the code doesn't have

## Language-specific tools

| Language | Dead code | Dependencies | Types |
|---|---|---|---|
| Go | `deadcode`, `go vet`, manual grep | `go list -json`, import analysis | grep for `any`/`interface{}` |
| TypeScript | `knip`, `ts-prune` | `madge`, `dependency-cruiser` | grep for `any`, `unknown`, `as any` |
| Python | `vulture`, `pylint` | `pydeps`, `import-linter` | grep for `Any`, `# type: ignore` |
| Java | IntelliJ inspections, `spotbugs` | `jdepend`, gradle dependencies | grep for `Object`, raw types |
| Rust | `cargo clippy`, dead_code warnings | `cargo tree` | rare — compiler enforces |

## Verification

After every change:
1. Build must pass
2. Tests must pass
3. No new warnings introduced

If build or tests fail after a change, **revert and document** — don't fix forward during a scrub.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall