# Boy Scout

> Incremental codebase cleanup following the Boy Scout Rule: 'Leave the code cleaner than you found it.' Run after implementing a feature, fixing a bug, or at any point to scan touched files for cleanup opportunities. Aggressively removes dead/unused code, refactors pure logic (only after writing tests), and cautiously reports UI cleanup opportunities without auto-refactoring them. Use when the user says 'boy scout', 'clean up', 'scout the code', 'any cleanup?', 'tidy up', or asks to check for tech debt, dead code, or incremental improvements.

- Skill: `kingly-clark/boy-scout` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kingly-clark/boy-scout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kingly-clark/boy-scout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kingly-clark (https://skillmd.com/u/kingly-clark)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kingly-clark/boy-scout

---


# Boy Scout

Scan recently changed or specified files for incremental cleanup opportunities. Apply safe fixes directly, refactor pure logic only with test coverage, and report UI concerns without touching them.

## Workflow

### 1. Determine Scope

Identify which files to scout:

- **After a feature/fix:** All files modified in the current branch (`git diff --name-only main...HEAD` or equivalent)
- **Explicit request:** Files or directories the user specifies
- **Current file:** The file the user is working in

### 2. Run the Tiered Cleanup

Read `references/cleanup-checklist.md` for the full checklist. Work through the tiers in order:

**Tier 1 — Safe Cleanup (apply directly):**
Remove dead code, fix naming, clean stale comments, organize imports. These changes cannot break behavior. Apply them immediately via edits.

**Tier 2 — Pure Logic Refactoring (test first, then refactor):**
For duplicated logic extraction, complex simplification, type safety improvements, and error handling fixes in non-UI code:

1. Identify the module and its public interface
2. Write a comprehensive test suite covering current behavior (happy path, edge cases, error paths)
3. Run the tests — all must pass
4. Apply the refactor in small, incremental steps
5. Run tests after each step to confirm nothing broke

Never skip the testing step. If tests cannot be written (no test framework, unclear behavior), report the opportunity instead of refactoring.

**Tier 3 — UI Components (report only):**
Scan UI components for issues but **do not refactor** unless every safety condition is met (see checklist). Instead, produce a findings report using the format in the checklist.

UI refactoring risks include:
- State corruption when component boundaries move
- Effect timing changes from shifted dependencies
- Memoization breakage causing handlers to change every render
- Race conditions from reordered async operations
- Focus/blur/keyboard event handling shifts

Only apply UI fixes that are purely additive and cannot affect state, effects, or rendering order (e.g., adding missing `key` props, `aria-*` attributes, or `alt` text).

### 3. Report Results

Summarize what was done and what remains:

```
## Boy Scout Report

### Applied (Tier 1)
- [list of safe cleanups applied with file:line references]

### Applied (Tier 2)
- [list of logic refactors applied, with test files created]

### UI Findings (Tier 3 — Manual Review Recommended)
- [list of UI opportunities with risk assessments]

### Deferred
- [anything skipped and why — e.g., no test framework, unclear behavior]
```

## Principles

- **Scope to what you touch.** Don't go hunting across the entire codebase. Focus on files that were recently modified or explicitly requested.
- **Minutes, not hours.** Each cleanup should be small. If a refactor would take more than ~15 minutes, report it as a separate task instead.
- **Never mix cleanup with new features.** Cleanup changes should be their own commit, separate from feature work.
- **When in doubt, report don't refactor.** Especially for UI. A false positive report costs nothing; a broken UI costs trust.
- **Tests are mandatory for Tier 2.** No exceptions. If you can't test it, you can't refactor it — just report it.