| name | polish |
| description | Run a repeatable codebase polish pass. Use when the user says 'polish', 'cleanup', 'tidy', 'housekeeping', or 'shine'. Runs all audit scripts, identifies safe fixes, implements them, and reports a before/after scorecard. Safe to run repeatedly — each pass finds diminishing returns. |
| version | 1.0.0 |
| metadata | {"tags":"cleanup, refactor, dead-code, imports, polish, audit"} |
RUNSTR Codebase Polish
Automated cleanup pass that finds and fixes low-risk issues. Each run produces a before/after scorecard. Safe to run on any branch — never changes business logic.
Rules
- NEVER change business logic, only structure and cleanup
- NEVER remove TODO comments that describe future work
- NEVER remove console.error or console.warn
- ALWAYS run
npm run typecheck after each fix category before committing
- ALWAYS verify removed symbols are truly unused (grep the file)
- Commit after each category with prefix
Cleanup: or Refactor:
- Stop and report if typecheck fails — do not push broken code
Execution
Step 1: Baseline Audit (run ALL in parallel)
Run every audit script and capture counts. These are the "before" numbers.
npx tsx scripts/verify/audit-dead-imports.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-file-size-limit.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-circular-dependencies.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-unbounded-queries.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-useeffect-cleanup.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-singleton-cleanup.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-hardcoded-strings.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-secret-exposure.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-service-error-handling.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-nostr-tools-usage.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-duplicate-constants.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-loading-state-coverage.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-empty-state-coverage.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-touchable-opacity-props.ts 2>&1 | tail -3
npx tsx scripts/verify/audit-charity-config-consistency.ts 2>&1 | tail -3
npm run typecheck 2>&1 | tail -3
Record the summary line from each script into a table.
Step 2: Dead Import Removal
Get the full list:
npx tsx scripts/verify/audit-dead-imports.ts 2>&1 | grep "^\[UNUSED\]"
For each unused import:
- Read the file
- Grep for the symbol name in the file (excluding the import line)
- If zero references found, remove the symbol from the import
- If removing it empties the import line, remove the whole line
Watch out for false positives: Type imports used in generics (useState<TypeName>) or type annotations may not be caught by simple grep. If the type name appears ANYWHERE in the file body, skip it.
Dispatch parallel agents for batches of 15-20 files. Run npm run typecheck after each batch. Commit when clean.
Step 3: Dead Commented Code
Search for and remove:
// REMOVED
// DEPRECATED
// OLD
// DISABLED
// DEAD
// UNUSED
Also find blocks of 3+ consecutive commented lines that are dead code (not documentation). Remove them.
DO NOT remove:
- TODO comments describing future work
- JSDoc or documentation comments
- Single-line comments explaining logic
- Intentionally disabled code with explanation (e.g., "DISABLED: causes crash on Android 12")
Commit when clean.
Step 4: Debug Console.log Removal
Search src/services/ and src/screens/ for debug logging:
console.log('DEBUG
console.log('test
console.log('here
console.log('===
console.log('---
console.log(`DEBUG
Also look for verbose banner-style logging (multi-line ==== blocks).
DO NOT remove:
console.error() or console.warn()- Operational logs with
[ServiceName] prefixes
- Logs inside catch blocks
- Initialization/lifecycle logs
Commit when clean.
Step 5: Stale Commented Imports
Search for commented-out import lines:
grep -rn "^[[:space:]]*// import " src/ --include="*.ts" --include="*.tsx"
Remove any that are clearly dead (no corresponding TODO, no explanation of why it was kept). Commit when clean.
Step 6: File Size Check
Run the file size audit. For any file over 1,500 lines, evaluate if it can be safely split:
- Settings screens -> section components
- Large services -> extract helper functions to separate files
- Large style blocks -> separate style files
Only split if the extraction is pure structural (no logic changes). Skip files where splitting would require interface changes across many consumers.
Step 7: Scorecard
Re-run ALL audit scripts from Step 1. Present a before/after table:
| Audit | Before | After | Delta |
|--------------------------|--------|-------|-------|
| typecheck | | | |
| dead-imports | | | |
| file-size-limit | | | |
| circular-dependencies | | | |
| unbounded-queries | | | |
| useeffect-cleanup | | | |
| singleton-cleanup | | | |
| hardcoded-strings | | | |
| secret-exposure | | | |
| service-error-handling | | | |
| nostr-tools-usage | | | |
| duplicate-constants | | | |
| loading-state-coverage | | | |
| empty-state-coverage | | | |
| touchable-opacity-props | | | |
| charity-config | | | |
Also report:
- Total files changed
- Net lines added/removed
- Commits created
- Anything that was flagged but too risky to fix (defer to next run)
Step 8: Score
Rate the pass 1-10:
- 9-10: Multiple audit numbers improved, zero regressions
- 7-8: Some improvements, minor items deferred
- 5-6: Mostly investigation, few fixes applied
- 1-4: Something went wrong or nothing was found
If score is 7+, the codebase got meaningfully cleaner. If score is 5 or below, the polish skill may have reached diminishing returns for this category of fixes — suggest new audit scripts or different polish targets.
