boy-scout-rule

name	boy-scout-rule
user-invocable	false
description	Use when modifying existing files, refactoring, improving code quality, or touching legacy code by applying the Boy Scout Rule to leave code better than you found it.
allowed-tools	["Read","Edit","Grep","Bash"]

Boy Scout Rule

"Leave the campground cleaner than you found it."

Always leave code better than you found it. Make incremental improvements when you touch a file.

What to Improve

Code Quality:

• Remove dead code (commented blocks, unused functions)
• Fix linting issues in files you touch
• Improve unclear naming (x, temp, data → descriptive)
• Add type annotations (TypeScript/Elixir @spec)
• Extract magic numbers to named constants
• Simplify complex logic
• Add missing error handling
• Update outdated comments
• Fix formatting
• Remove unused imports/variables
• Consolidate duplication

What NOT to Do

• ❌ Massive unrelated refactors
• ❌ Change behavior without tests
• ❌ Fix everything in the file (stay focused)
• ❌ Breaking changes without tests
• ❌ Premature optimization
• ❌ Change unrelated sections

Process

1. Before changes: Read file, note obvious issues, run linter
2. Make primary changes: Implement feature/fix, write tests
3. Apply improvements: Fix linting, improve naming, add types, extract constants, remove dead code
4. Run verification: mix lint && mix test or yarn test:lint && yarn ts:check && yarn test
5. Document: Include boy scout changes in commit message

Example Commit Message

Add worker search filter

- Implement location-based filtering
- Add tests for search radius

Boy Scout improvements:
- Extract SEARCH_RADIUS constant
- Add type annotations to helper functions
- Remove unused import statements
- Improve variable naming in search logic

Example Improvements

Before:

function calculateTotal(items) {  // No types
  let t = 0;  // Poor naming
  for (let i = 0; i < items.length; i++) {  // Old-style
    t += items[i].price * 1.08;  // Magic number
  }
  return t;
}

After:

const TAX_RATE = 1.08;

function calculateTotal(items: Item[]): number {
  return items.reduce((total, item) => {
    return total + (item.price * TAX_RATE);
  }, 0);
}

Improvements: types, constant, naming, modern syntax, simplified.

Critical Rules

• Keep improvements in same commit as primary changes
• Focus on "blast radius" (code near your changes)
• Prioritize readability over cleverness
• Always run full test suite after improvements
• Ask for help when unsure about business logic
• Small improvements > perfect refactors

Checklist

• Removed dead code in files I touched
• Fixed linting issues
• Improved naming where I made changes
• Added type annotations where missing
• Extracted magic numbers
• Updated outdated comments
• Removed unused imports
• Simplified complex logic
• Added error handling
• All tests pass
• No new linting errors
• Documented in commit message

Integration

During implementation: Make changes, apply boy scout, verify, commit together

During code review: Look for boy scout opportunities, recognize good boy scouting

During bug fixes: Fix bug, improve surrounding code, add tests, clean up

Remember

Incremental improvement, not perfection

• Small improvements compound over time
• Every file touched is an opportunity
• Be a good steward of the codebase
• When in doubt, ask for review on larger improvements