Cleanup — Remove Code Noise

Detect and optionally remove code noise — debug prints, transitional/obvious comments, and commented-out code — across languages. Pairs with smart-commit.

skilladaptablecrossconventions

# Cleanup — Remove Code Noise

Detect and optionally remove transitional comments, debug code, obvious comments, and commented-out code. Repository-agnostic: grep patterns cover the common languages, and the high-value pass — judging *obvious* comments — is purely semantic.

## Arguments
$ARGUMENTS

## Flags
- `--all`: check all source files in the repo's source dirs.
- `--branch`: check files changed vs the base branch.
- `--quiet`: only output if issues are found.
- `--fix`: remove detected issues (prompts before each).

**Default** (no scope flag): only check uncommitted changes (staged + unstaged).

**Exception:** a line tagged `cleanup: intentional` is always skipped.

## Detection Patterns (grep-detectable)

| Category | Pattern (extend per language) | Example |
|---|---|---|
| Transitional comments | `previously`, `was:`, `changed from`, ` now `, `moved to`, `old:`, `before:`, `used to` | `// Padding now handled by X` |
| Commented-out code | a comment that wraps a statement: `^\s*(//|#)\s*(let\|var\|const\|func\|def\|class\|fn\|return\|if\|for\|import) ` (excludes doc comments `///`, `##`, `"""`) | `// let x = 5` |
| Debug prints | `console.log(`, `print(`, `println!`, `fmt.Print`, `System.out.print`, `dump(`, `debugPrint(`, `puts ` | `console.log("debug", value)` |
| Logger debug | `log.debug(`, `logger.debug(`, `NSLog(`, `os_log(` with debug text | `logger.debug("state", state)` |
| Completed TODOs | `TODO.*(done\|completed\|fixed)` | `// TODO: done` |
| Empty section markers | `// MARK: -$`, `# region` with nothing after | `// MARK: -` |

## Manual Review: Obvious Comments

Comments that restate what the code already says add no value and become maintenance debt. These need semantic judgment — grep can't find them.

**Remove comments that:**
- Restate the name: `/* Feature for managing coins */` on `class CoinsFeature`
- Describe obvious behavior: `// Set loading to true` above `isLoading = true`
- Echo the type/signature: `/* the user client */` on `userClient: UserClient`
- Narrate self-documenting code: `// Check if user has enough coins` above `if balance >= price`

**Keep comments that explain:**
- **Why**, not what: `// Defer setup to avoid blocking the main thread`
- Non-obvious trade-offs: `// O(n) search is fine — list is always < 50 items`
- External constraints: `// Provider requires this entitlement check before unlock`
- Workarounds: `// Platform bug — force-unwrap is safe here (see TICKET-123)`
- Business rules: `// 20% discount applies to bundle purchases`

## Workflow

### 1. Get files

```bash
# Base branch for --branch (auto-detected)
if git ls-remote --heads origin develop | grep -q .; then BASE_BRANCH=develop
else BASE_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p'); BASE_BRANCH=${BASE_BRANCH:-main}; fi

if   echo "$ARGUMENTS" | grep -q -- "--all";    then FILES=$(git ls-files $SRC_DIRS 2>/dev/null)
elif echo "$ARGUMENTS" | grep -q -- "--branch"; then FILES=$(git diff "$BASE_BRANCH..HEAD" --name-only)
else FILES=$({ git diff --name-only; git diff --cached --name-only; } | sort -u)
fi
```

### 2. Phase 1 — grep-detectable

Run the pattern table above over `$FILES`, excluding lines tagged `cleanup: intentional`:

```bash
PATTERNS=(
  '// .*(previously|was:|changed from| now |moved to|old:|before:|used to)'
  '^[[:space:]]*(//|#)[[:space:]]*(let|var|const|func|def|class|fn|return|if|for|import|public|private)[[:space:]]'
  'console\.log\(|[^a-zA-Z]print\(|println!|fmt\.Print|System\.out\.print|debugPrint\(|dump\(|puts '
  '(log|logger)\.debug\(|NSLog\(|os_log\('
  '//[[:space:]]*TODO.*(done|completed|fixed|DONE|COMPLETED|FIXED)'
)
for p in "${PATTERNS[@]}"; do
  grep -rnE "$p" $FILES 2>/dev/null | grep -v "cleanup: intentional"
done
```

### 3. Phase 2 — semantic review (REQUIRED)

After grep, read the actual `git diff` and identify obvious comments using the rules above. List each as `file:line: comment → the code it restates`.

### 4. Report or fix

- `--quiet`: only show the count.
- `--fix`: remove grep-detected issues, then ask about each obvious comment.
- Default: list all issues (grep + semantic), modify nothing.

## Output Format

```
Checking uncommitted changes…

Phase 1 — grep-detectable
  src/checkout/charge.ts:42  console.log("amount", amount)
  src/checkout/charge.ts:88  // old: used the legacy gateway

Phase 2 — obvious comments (semantic)
  src/cart/cart.ts:21  // add item to cart  →  cart.push(item)
  src/cart/cart.ts:55  // the total          →  let total: number

Want me to remove these?
```

## Integration

Called automatically by `smart-commit` as a pre-commit warning: it runs detection (report-only), shows warnings, offers to fix, and lets you continue anyway — **issues are warnings, not blockers**.

## Important
- **Warning only** — never blocks a commit.
- Keep a legitimate transitional comment with `// cleanup: intentional`.
- Default mode reports without modifying; `--fix` applies removals with confirmation.

## Supporting File
- [`detection-patterns.md`](detection-patterns.md) — the full per-language pattern reference and edge cases.

How to use it

Comes with the ai-devkit plugin (install — two commands). Once installed, type this in any repo:

/cleanup --branch

You can also just describe the task in plain words — the agent picks the skill up by itself. That’s the Claude Code form — in Codex, type $cleanup instead, or just name the skill in plain words.

What a run looks like:

your-repo — claude

> /cleanup --branch ⏺ Scanning the branch diff for code noise…⏺ Found: 2 debug prints · 1 commented-out block · 3 obvious comments ✓ Report ready — re-run with --fix to remove them

That’s all you do — the agent runs the whole workflow itself. Curious, or want to audit it? The playbook it follows is collapsed under Under the hood below.

See it in action

cleanup — uncommitted changes

function charge(amount) {

console.log("amount", amount)

// old: legacy gateway path

const fee = amount * 0.029

// const legacyFee = amount * 0.05

const total = amount + fee

debugPrint("charged", total)

return total

}

Under the hood — the playbook the agent follows nothing in here is for you to run

Everything in this section is read and executed by the agent when you invoke the skill. It’s published so you can audit it, learn from it, or adapt it — not because you need to follow it yourself.

Arguments#

$ARGUMENTS

Flags#

--all: check all source files in the repo's source dirs.
--branch: check files changed vs the base branch.
--quiet: only output if issues are found.
--fix: remove detected issues (prompts before each).

Default (no scope flag): only check uncommitted changes (staged + unstaged).

Exception: a line tagged cleanup: intentional is always skipped.

Detection Patterns (grep-detectable)#

Category	Pattern (extend per language)	Example
Transitional comments	`previously`, `was:`, `changed from`, `now` , `moved to`, `old:`, `before:`, `used to`	`// Padding now handled by X`
Commented-out code	a comment that wraps a statement: `^\s*(//	#)\s*(let\	var\	const\	func\	def\	class\	fn\	return\	if\	for\	import) `(excludes doc comments` ///`,` ##`,` """`)	`// let x = 5`
Debug prints	`console.log(`, `print(`, `println!`, `fmt.Print`, `System.out.print`, `dump(`, `debugPrint(`, `puts`	`console.log("debug", value)`
Logger debug	`log.debug(`, `logger.debug(`, `NSLog(`, `os_log(` with debug text	`logger.debug("state", state)`
Completed TODOs	`TODO.*(done\	completed\	fixed)`	`// TODO: done`
Empty section markers	`// MARK: -$`, `# region` with nothing after	`// MARK: -`

Manual Review: Obvious Comments#

Comments that restate what the code already says add no value and become maintenance debt. These need semantic judgment — grep can't find them.

Remove comments that:

Restate the name: / Feature for managing coins / on class CoinsFeature
Describe obvious behavior: // Set loading to true above isLoading = true
Echo the type/signature: / the user client / on userClient: UserClient
Narrate self-documenting code: // Check if user has enough coins above if balance >= price

Keep comments that explain:

Why, not what: // Defer setup to avoid blocking the main thread
Non-obvious trade-offs: // O(n) search is fine — list is always < 50 items
External constraints: // Provider requires this entitlement check before unlock
Workarounds: // Platform bug — force-unwrap is safe here (see TICKET-123)
Business rules: // 20% discount applies to bundle purchases

Workflow#

1. Get files#

# Base branch for --branch (auto-detected)
if git ls-remote --heads origin develop | grep -q .; then BASE_BRANCH=develop
else BASE_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p'); BASE_BRANCH=${BASE_BRANCH:-main}; fi

# Discover the repo's source roots instead of hardcoding them
SRC_DIRS=$(git ls-files | sed -n 's#^\(src\|lib\|pkg\|app\|internal\|Sources\)/.*#\1#p' | sort -u)

if   echo "$ARGUMENTS" | grep -q -- "--all";    then FILES=$(git ls-files $SRC_DIRS 2>/dev/null)
elif echo "$ARGUMENTS" | grep -q -- "--branch"; then FILES=$(git diff "$BASE_BRANCH..HEAD" --name-only)
else FILES=$({ git diff --name-only; git diff --cached --name-only; } | sort -u)
fi

2. Phase 1 — grep-detectable#

Run the pattern table above over $FILES, excluding lines tagged cleanup: intentional:

PATTERNS=(
  '// .*(previously|was:|changed from| now |moved to|old:|before:|used to)'
  '^[[:space:]]*(//|#)[[:space:]]*(let|var|const|func|def|class|fn|return|if|for|import|public|private)[[:space:]]'
  'console\.log\(|[^a-zA-Z]print\(|println!|fmt\.Print|System\.out\.print|debugPrint\(|dump\(|puts '
  '(log|logger)\.debug\(|NSLog\(|os_log\('
  '//[[:space:]]*TODO.*(done|completed|fixed|DONE|COMPLETED|FIXED)'
)
for p in "${PATTERNS[@]}"; do
  grep -rnE "$p" $FILES 2>/dev/null | grep -v "cleanup: intentional"
done

3. Phase 2 — semantic review (REQUIRED)#

After grep, read the actual git diff and identify obvious comments using the rules above. List each as file:line: comment → the code it restates.

4. Report or fix#

--quiet: only show the count.
--fix: remove grep-detected issues, then ask about each obvious comment.
Default: list all issues (grep + semantic), modify nothing.

Output Format#

Checking uncommitted changes…

Phase 1 — grep-detectable
  src/checkout/charge.ts:42  console.log("amount", amount)
  src/checkout/charge.ts:88  // old: used the legacy gateway

Phase 2 — obvious comments (semantic)
  src/cart/cart.ts:21  // add item to cart  →  cart.push(item)
  src/cart/cart.ts:55  // the total          →  let total: number

Want me to remove these?

Integration#

Called automatically by smart-commit as a pre-commit warning: it runs detection (report-only), shows warnings, offers to fix, and lets you continue anyway — issues are warnings, not blockers.

Important#

Warning only — never blocks a commit.
Keep a legitimate transitional comment with // cleanup: intentional.
Default mode reports without modifying; --fix applies removals with confirmation.

Supporting File#

detection-patterns.md — the full per-language pattern reference and edge cases.

Adapt it to another stack ready-made prompt for Claude / Codex

Adapt to your platform

Copy this prompt into Claude or Codex, fill in your stack, and it will generate an adapted version for your project.

Port an agent skill (Claude Code / Codex SKILL.md format) to my project.

Below is "cleanup" from ai-devkit (origin platform: cross, portability: adaptable).
What it does: Detect and optionally remove code noise — debug prints, transitional/obvious comments, and commented-out code — across languages. Pairs with smart-commit.

Read it, then produce an equivalent SKILL.md (plus any scripts) for MY project:
<describe your stack, conventions, and repo here>

Keep the workflow's structure and intent. Replace platform-specific tooling and references per these notes:
The grep-detectable patterns are listed per-language — keep the ones for your stack and drop the rest, or extend the table. The 'obvious comments' semantic-review section (the highest-value part) is fully language-agnostic and ports verbatim. --all paths and the --branch base are auto-detected. Designed to be called by smart-commit as a pre-commit warning; works standalone too.

List what you changed and why.

--- SKILL.md ---
# Cleanup — Remove Code Noise

Detect and optionally remove transitional comments, debug code, obvious comments, and commented-out code. Repository-agnostic: grep patterns cover the common languages, and the high-value pass — judging *obvious* comments — is purely semantic.

## Arguments
$ARGUMENTS

## Flags
- `--all`: check all source files in the repo's source dirs.
- `--branch`: check files changed vs the base branch.
- `--quiet`: only output if issues are found.
- `--fix`: remove detected issues (prompts before each).

**Default** (no scope flag): only check uncommitted changes (staged + unstaged).

**Exception:** a line tagged `cleanup: intentional` is always skipped.

## Detection Patterns (grep-detectable)

| Category | Pattern (extend per language) | Example |
|---|---|---|
| Transitional comments | `previously`, `was:`, `changed from`, ` now `, `moved to`, `old:`, `before:`, `used to` | `// Padding now handled by X` |
| Commented-out code | a comment that wraps a statement: `^\s*(//|#)\s*(let\|var\|const\|func\|def\|class\|fn\|return\|if\|for\|import) ` (excludes doc comments `///`, `##`, `"""`) | `// let x = 5` |
| Debug prints | `console.log(`, `print(`, `println!`, `fmt.Print`, `System.out.print`, `dump(`, `debugPrint(`, `puts ` | `console.log("debug", value)` |
| Logger debug | `log.debug(`, `logger.debug(`, `NSLog(`, `os_log(` with debug text | `logger.debug("state", state)` |
| Completed TODOs | `TODO.*(done\|completed\|fixed)` | `// TODO: done` |
| Empty section markers | `// MARK: -$`, `# region` with nothing after | `// MARK: -` |

## Manual Review: Obvious Comments

Comments that restate what the code already says add no value and become maintenance debt. These need semantic judgment — grep can't find them.

**Remove comments that:**
- Restate the name: `/* Feature for managing coins */` on `class CoinsFeature`
- Describe obvious behavior: `// Set loading to true` above `isLoading = true`
- Echo the type/signature: `/* the user client */` on `userClient: UserClient`
- Narrate self-documenting code: `// Check if user has enough coins` above `if balance >= price`

**Keep comments that explain:**
- **Why**, not what: `// Defer setup to avoid blocking the main thread`
- Non-obvious trade-offs: `// O(n) search is fine — list is always < 50 items`
- External constraints: `// Provider requires this entitlement check before unlock`
- Workarounds: `// Platform bug — force-unwrap is safe here (see TICKET-123)`
- Business rules: `// 20% discount applies to bundle purchases`

## Workflow

### 1. Get files

```bash
# Base branch for --branch (auto-detected)
if git ls-remote --heads origin develop | grep -q .; then BASE_BRANCH=develop
else BASE_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p'); BASE_BRANCH=${BASE_BRANCH:-main}; fi

# Discover the repo's source roots instead of hardcoding them
SRC_DIRS=$(git ls-files | sed -n 's#^\(src\|lib\|pkg\|app\|internal\|Sources\)/.*#\1#p' | sort -u)

if   echo "$ARGUMENTS" | grep -q -- "--all";    then FILES=$(git ls-files $SRC_DIRS 2>/dev/null)
elif echo "$ARGUMENTS" | grep -q -- "--branch"; then FILES=$(git diff "$BASE_BRANCH..HEAD" --name-only)
else FILES=$({ git diff --name-only; git diff --cached --name-only; } | sort -u)
fi
```

### 2. Phase 1 — grep-detectable

Run the pattern table above over `$FILES`, excluding lines tagged `cleanup: intentional`:

```bash
PATTERNS=(
  '// .*(previously|was:|changed from| now |moved to|old:|before:|used to)'
  '^[[:space:]]*(//|#)[[:space:]]*(let|var|const|func|def|class|fn|return|if|for|import|public|private)[[:space:]]'
  'console\.log\(|[^a-zA-Z]print\(|println!|fmt\.Print|System\.out\.print|debugPrint\(|dump\(|puts '
  '(log|logger)\.debug\(|NSLog\(|os_log\('
  '//[[:space:]]*TODO.*(done|completed|fixed|DONE|COMPLETED|FIXED)'
)
for p in "${PATTERNS[@]}"; do
  grep -rnE "$p" $FILES 2>/dev/null | grep -v "cleanup: intentional"
done
```

### 3. Phase 2 — semantic review (REQUIRED)

After grep, read the actual `git diff` and identify obvious comments using the rules above. List each as `file:line: comment → the code it restates`.

### 4. Report or fix

- `--quiet`: only show the count.
- `--fix`: remove grep-detected issues, then ask about each obvious comment.
- Default: list all issues (grep + semantic), modify nothing.

## Output Format

```
Checking uncommitted changes…

Phase 1 — grep-detectable
  src/checkout/charge.ts:42  console.log("amount", amount)
  src/checkout/charge.ts:88  // old: used the legacy gateway

Phase 2 — obvious comments (semantic)
  src/cart/cart.ts:21  // add item to cart  →  cart.push(item)
  src/cart/cart.ts:55  // the total          →  let total: number

Want me to remove these?
```

## Integration

Called automatically by `smart-commit` as a pre-commit warning: it runs detection (report-only), shows warnings, offers to fix, and lets you continue anyway — **issues are warnings, not blockers**.

## Important
- **Warning only** — never blocks a commit.
- Keep a legitimate transitional comment with `// cleanup: intentional`.
- Default mode reports without modifying; `--fix` applies removals with confirmation.

## Supporting File
- [`detection-patterns.md`](detection-patterns.md) — the full per-language pattern reference and edge cases.