Vibe-Code Cleanup — Production Refactor Skill

A safe, incremental cleanup workflow for AI-generated / vibe-coded fullstack apps. The goal is to make the codebase production-ready without breaking anything that already works.

When to Use

• Use when a rapidly built app works but has broken imports, duplicated logic, dead code, unclear environment variables, or fragile release hygiene.
• Use before launch or handoff to convert exploratory code into a maintainable production baseline.
• Use when cleanup must preserve existing behavior and avoid broad rewrites of routes, APIs, auth, data models, or integrations.

Core Philosophy

> Surgery, not demolition. Remove only what is provably dead. Preserve everything else.

Never:

• Rewrite working systems for cosmetic reasons
• Rename routes, slugs, or API endpoints that may be indexed or cached
• Change tool inputs/outputs, API contracts, DB schema, or auth flow
• Delete files you haven't verified are unused
• Make broad sweeping changes in a single commit

Always:

• Make small, targeted, reversible changes
• Validate after every meaningful batch of changes
• Prefer shared helpers over copy-pasted blocks
• Keep backward compatibility

Step 1 — Reconnaissance (read before touching)

Before changing anything, map the codebase:

bash
# List all pages/routes
find . -type f \( -name 'page.js' -o -name 'page.jsx' -o -name 'page.ts' -o -name 'page.tsx' \)
find pages -type f \( -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx' \) | rg -v '/_' | sort

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

# Find unused exports (optional, for larger projects)
npx ts-prune 2>/dev/null | head -40

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

Document what you find. Do NOT change yet.

Step 2 — Fix Broken Imports First

Broken imports cause build failures and should be fixed before anything else.

bash
# TypeScript: list all errors
npx tsc --noEmit 2>&1

# Common patterns to fix:
# - Missing file (file was deleted or renamed)
# - Wrong relative path (../lib vs ../../lib)
# - Named export that doesn't exist

Fix rule: Fix the import reference. Do NOT delete the referenced file unless you've confirmed it's unused everywhere.

Step 3 — Identify Dead Code (verify before removing)

A file/export is safe to remove only if:

1. No other file imports it (grep-confirmed)
2. It's not referenced in config, sitemap, or route manifest
3. It's not a public-facing URL (page.js, route.js)

bash
# Check if a file is imported anywhere
grep -r "from.*my-file\|require.*my-file" --include="*.{js,ts,jsx,tsx}" .

# Check if a component is used anywhere  
grep -r "MyComponent" --include="*.{js,ts,jsx,tsx}" .

Step 4 — Consolidate Repeated Logic into Helpers

Look for repeated patterns (metadata blocks, API fetch wrappers, error handlers) that appear in 3+ places.

Good consolidation targets:

• Page-level SEO metadata (Open Graph, Twitter cards, canonical)
• Fetch wrappers with error handling
• Repeated utility functions (slugify, formatDate, truncate)

Bad consolidation targets (leave alone):

• One-off business logic
• Route handlers with different contracts
• Anything touching DB schema or auth

Pattern for shared metadata helper (Next.js):

js
// lib/socialMetadata.js
export function buildPageMetadata({ title, description, path, image }) {
  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'https://yourdomain.com';
  const imageUrl = image?.startsWith('http') ? image : `${baseUrl}${image}`;
  
  return {
    title,
    description,
    openGraph: {
      title,
      description,
      url: `${baseUrl}${path}`,
      images: [{ url: imageUrl, width: 1200, height: 630, alt: title }],
    },
    twitter: {
      card: 'summary_large_image',
      title,
      description,
      images: [imageUrl],
    },
    alternates: {
      canonical: `${baseUrl}${path}`,
    },
  };
}

Step 5 — Environment Variable Audit

bash
# List all env vars used in code
grep -r "process\.env\." --include="*.{js,ts,jsx,tsx}" . | grep -oP 'process\.env\.\w+' | sort -u

# Compare against .env.example or .env.local
cat .env.example 2>/dev/null || cat .env.local 2>/dev/null

Flag any env vars used in code but missing from .env.example. Never add secrets to version control.

Step 6 — Validate After Every Batch

Run this after every meaningful batch of cleanup changes:

bash
# 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

If build or typecheck breaks → revert the last batch before continuing.

Step 7 — Commit Strategy

Each commit should be a single logical unit:

text
fix: remove broken import in app/blog/page.js
refactor: consolidate social metadata into lib/socialMetadata.js  
chore: remove verified-unused utils/oldHelper.js
fix: standardize env var references to NEXT_PUBLIC_BASE_URL

Never bundle UI changes + logic changes + file deletions in one commit. Smaller commits = easier rollback.

What NOT to Clean Up

Treat these as off-limits unless there's a verified bug:

| Area | Why | |------|-----| | Route slugs / page paths | May be indexed by Google | | API route contracts | Callers depend on exact shape | | DB schema / Prisma models | Migration required | | Auth flow logic | Security-sensitive | | Third-party integration configs | Keys/webhooks are environment-specific | | Working tool pages | User-facing functionality |

Cleanup Checklist

• ] TypeScript errors fixed
• ] No broken imports
• ] Dead code removed (grep-verified)
• ] Shared helpers created for repeated patterns (3+ uses)
• ] No hardcoded secrets or local-only URLs
• ] All env vars documented in .env.example
• ] Build passes
• ] Tests pass (or no tests exist)
• ] Lint passes
• ] Each commit is scoped and explainable

Limitations

• Does not infer product intent from code alone; confirm behavior before deleting routes, components, API contracts, or data models.
• Cleanup should be applied in small reviewed batches because broad refactors can hide regressions.
• Avoid changing auth, billing, persistence, or third-party integration behavior without explicit requirements and tests.