/repo-polish

Quick Reference: Create branch → Rapid assessment → Parallel deep scan (3 agents) → Fix all issues → Verify after each batch → Push & create PR.

Fully autonomous codebase improvement. Creates branch, fixes everything it finds, raises PR.

Philosophy

True fire and forget: Invoke, walk away, come back to a PR ready for review.

• Fix everything found (the PR is the approval gate)
• Verify after each change batch (revert if tests break)
• Atomic commits with clear messages
• All work encapsulated in a PR

Step 1: Branch Setup

# Capture current branch
ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Pull latest
git pull 2>/dev/null || true

# Create polish branch with timestamp
POLISH_BRANCH="polish/$(date +%Y%m%d-%H%M%S)"
git checkout -b "$POLISH_BRANCH"

Store the original branch name - we'll PR back to it when done.

Step 2: Rapid Assessment

Quickly gather context:

• Project type (package.json, Cargo.toml, requirements.txt, etc.)
• Build/test commands available
• Current test/lint status
• File structure overview

Output a one-liner summary:

[tech stack] | [X files] | [build status] | [test status]

Step 3: Parallel Deep Scan

Launch specialized agents simultaneously using Task tool:

Agent 1 - Quick Wins Scanner:

• Unused imports/variables
• Console.log/print debug statements
• Commented-out code blocks
• Trailing whitespace, formatting issues
• Empty files or dead exports

Agent 2 - Code Quality Scanner:

• TODO/FIXME items (document or resolve)
• Type safety gaps
• Error handling holes
• Duplicated logic
• Inconsistent patterns

Agent 3 - DX & Docs Scanner:

• README accuracy vs actual setup
• Missing/outdated documentation
• Unclear error messages
• Missing examples

Step 4: Fix Everything

Fix all issues found. Group by category and commit atomically.

Fix Categories (in order)

1. Mechanical cleanup

• Remove unused imports
• Remove console.log/debug statements (unless in logging utilities)
• Remove commented-out code
• Fix typos in comments/strings
• Remove trailing whitespace
• Remove empty files with no exports
• Sort imports (if project has convention)
• Fix formatting (match project style)

2. Code quality

• Add missing error handling
• Fix type safety issues
• Resolve or document TODOs
• Extract duplicated logic
• Standardize inconsistent patterns

3. Developer experience

• Update README if inaccurate
• Improve error messages
• Add missing documentation for public APIs

After each category:

# Detect package manager from lockfile
if [ -f "bun.lockb" ]; then
    PM="bun"
elif [ -f "pnpm-lock.yaml" ]; then
    PM="pnpm"
elif [ -f "yarn.lock" ]; then
    PM="yarn"
else
    PM="npm"
fi

# Verify nothing broke
$PM run build 2>/dev/null || true
$PM run test 2>/dev/null || true

If tests fail after a fix, immediately revert that specific change and continue.

Commit Pattern

git add -A && git commit -m "chore: [specific improvement]"

One commit per logical fix type (e.g., "chore: remove unused imports", "fix: add error handling to API calls").

Step 5: Push & Create PR

After all fixes are complete:

# Push the polish branch
git push -u origin "$POLISH_BRANCH"

# Create PR back to original branch
gh pr create \
  --base "$ORIGINAL_BRANCH" \
  --title "chore: repository polish $(date +%Y-%m-%d)" \
  --body "$(cat <<'EOF'
## Summary
Automated repository polish pass.

### Changes
[List each commit with brief description]

### Stats
- Files changed: X
- Insertions: +X
- Deletions: -X

### Verification
- [x] Build passes
- [x] Tests pass (or N/A)
- [x] No behavioral changes

---
*Generated by `/repo-polish`*
EOF
)"

Output the PR URL.

If gh CLI is not available or not authenticated:

Polish complete on branch: polish/YYYYMMDD-HHMMSS
Push and create PR manually:
  git push -u origin [branch]
  https://github.com/[owner]/[repo]/compare/[original]...[branch]

Constraints

• Never break tests - revert immediately if tests fail
• Never change behavior - only improve quality/clarity
• Never touch .env or secrets - skip entirely
• Never modify generated files - skip lock files, build output, etc.
• Match existing style - don't impose new conventions

Execution Notes

1. Use TodoWrite to track progress visibly
2. Launch scan agents in parallel for speed
3. Group similar fixes into single commits
4. Always run verification after changes
5. If no build/test commands exist, be more conservative
6. Prefer many small improvements over few large ones
7. The PR description should list all changes made