Safely refactor AI-generated code for production

Runs a safe, incremental cleanup workflow for AI-generated ("vibe-coded") full-stack apps aimed at production-readiness without breaking anything that already works, under the philosophy "surgery, not demolition - remove only what is provably dead, preserve everything else." It never rewrites working systems for cosmetic reasons, renames routes, slugs, or API endpoints that might be indexed or cached, changes API contracts, DB schema, or auth flow, deletes an unverified-unused file, or makes broad sweeping changes in one commit; it always makes small, targeted, reversible changes, validates after every meaningful batch, prefers shared helpers over copy-pasted blocks, and keeps backward compatibility. The process runs in order: reconnaissance first (map all routes and pages, run a TypeScript check for broken imports, optionally find unused exports, grep for leftover console.log/debugger/TODO markers) without changing anything yet; fix broken imports before anything else, by fixing the reference rather than deleting the referenced file unless it is confirmed unused everywhere; identify dead code as safe to remove only if grep confirms nothing imports it, it is not referenced in config, sitemap, or route manifests, and it is not a public-facing page or route file; consolidate genuinely repeated logic (SEO metadata blocks, fetch wrappers with error handling, utility functions) that appears in 3+ places into shared helpers, while leaving one-off business logic, differently-shaped route handlers, and anything touching DB schema or auth alone; audit environment variables used in code against .env.example, flagging any that are used but undocumented, never committing secrets; validate after every batch with a typecheck, lint, build, and test run, reverting the last batch if any of those breaks; and commit each logical change separately rather than bundling UI changes, logic changes, and file deletions into one commit.

Use it when a rapidly built app works but has broken imports, duplicated logic, dead code, unclear environment variables, or fragile release hygiene, before launch or handoff to convert exploratory code into a maintainable production baseline, or when cleanup must preserve existing behavior without broad rewrites of routes, APIs, auth, data models, or integrations. Certain areas are off-limits unless there's a verified bug: route slugs or page paths (may be indexed by Google), API route contracts (callers depend on the exact shape), DB schema or ORM models (needs a migration), auth flow logic (security-sensitive), third-party integration configs (environment-specific keys and webhooks), and working, user-facing tool pages. It does not infer product intent from code alone, so behavior should be confirmed before deleting routes, components, API contracts, or data models, and cleanup should land in small reviewed batches since broad refactors can hide regressions.

Input is the existing app's source tree. Reconnaissance commands:

### Find broken imports (TS projects)
npx tsc --noEmit 2>&1 | head -80

### Check for console.log / debug leftovers
grep -r "console\.log\|debugger\|TODO\|FIXME\|HACK" --include="*.{js,ts,jsx,tsx}" -l

Validation after every batch:

### TypeScript check
npx tsc --noEmit

### Lint
npx eslint . --ext .js,.jsx,.ts,.tsx --max-warnings 0

### Build (catches runtime issues TypeScript misses)
npm run build

### Tests (if present)
npm test -- --runInBand --passWithNoTests

Output is a series of small, scoped commits (a broken-import fix, a metadata-helper consolidation, a verified-dead-file removal, an env-var standardization) and a final checklist confirming no TypeScript errors, no broken imports, grep-verified dead code removal, shared helpers for 3+ use patterns, no hardcoded secrets, documented env vars, and passing build, tests, and lint.

Relies on standard JS/TS tooling - tsc --noEmit, eslint, npm run build, npm test, optionally ts-prune for unused-export detection - plus grep/ripgrep for import and usage verification, and .env.example as the source of truth for documented environment variables.

Teams shipping an AI-generated or rapidly prototyped full-stack app who need it production-ready before launch or handoff - fixing broken imports, removing genuinely dead code, and consolidating real duplication - without touching routes, API contracts, schema, or auth that already work.