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.