simplify-codebase

Codebase Simplify

Orchestrate a full post-refactoring cleanup by analyzing what's fresh, what's stale, and what's dead, then simplifying the good code and archiving the rest.

Three-Agent Architecture

This skill delegates to three specialized agents:

1. staleness-analyzer — Classifies every file as FRESH, STALE, or DEAD using git history, import/dependency graphs, and framework awareness. Produces a scored inventory with confidence ratings.

2. code-simplifier — Operates only on FRESH files. Simplifies code for clarity and consistency while preserving functionality. Follows project standards from CLAUDE.md.

3. stale-archiver — Moves DEAD files to _archive/ preserving directory structure and git history. Maintains ARCHIVE_LOG.md with full provenance.

Phase 1: Initialize

Pre-Flight Checks

1. Run git status --porcelain. If non-empty, abort:

   "Working tree has uncommitted changes. Commit or stash before running."

2. Check for simplify-progress.json at the project root:

   • If it exists with pending phases, skip to Resume.
   • If it exists and all phases are complete, report completion and stop.
   • If it doesn't exist, continue.

Detect Project Type

Identify the project's language/framework to configure the staleness-analyzer:

Signal	Type
package.json + next.config.*	Next.js/React
convex/ directory	Convex backend
*.csproj or *.sln	.NET/C#
pyproject.toml or setup.py	Python
Cargo.toml	Rust
go.mod	Go

Store the detected type. This determines which import patterns and framework entrypoints the staleness-analyzer checks.

Discover Test Command

Resolve in priority order:

1. CLAUDE.md — "Commands" or "Common Commands" section
2. package.json — scripts.test
3. pyproject.toml — [tool.pytest] or [tool.hatch]
4. Makefile — test target
5. If none found, ask the user.

Write Progress File

Create simplify-progress.json:

{
  "started": "2026-03-09",
  "projectType": "nextjs-convex",
  "testCommand": "npm test",
  "stalenessWindow": 30,
  "phases": {
    "analyze": "pending",
    "simplify": "pending",
    "archive": "pending",
    "verify": "pending"
  },
  "inventory": null,
  "commits": [],
  "errors": []
}

Phase 2: Analyze (staleness-analyzer agent)

Invoke the staleness-analyzer agent scoped to the entire project.

The agent will:

1. Identify all files modified in the staleness window (default 30 days)
2. Build a dependency/import graph
3. Classify every source file as FRESH, STALE, or DEAD with confidence scores
4. Produce a markdown inventory table

After the inventory is produced:

1. Present the inventory to the user as a summary:

   "Found N fresh files, M stale files, and K dead files (confidence 60+). Here are the dead files I recommend archiving:" [table of DEAD files]

2. Ask for confirmation before proceeding:

   "Should I proceed with simplifying the fresh code and archiving the dead files? You can also exclude specific files."

3. Save the inventory to simplify-progress.json.

4. Update phase: "analyze": "done".

Phase 3: Simplify (code-simplifier agent)

For each module containing FRESH files, invoke the code-simplifier agent.

Module Discovery

Group fresh files by their top-level directory:

• src/dashboard/*.tsx = one module
• src/api/*.ts = another module
• convex/*.ts = another module

If any module has 20+ files, split into sub-batches of ~10.

Module Loop

For each module:

1. Invoke the code-simplifier agent scoped to that module

2. Run the test command

3. Tests pass: auto-commit with message:

   refactor: simplify <module-path>
   
   <bullet summary of changes>
   
   Co-Authored-By: Claude <noreply@anthropic.com>
   

4. Tests fail: revert with git checkout -- ., log the failure, skip

5. Update simplify-progress.json with commit SHA or skip reason

After all modules: update phase "simplify": "done".

Phase 4: Archive (stale-archiver agent)

Invoke the stale-archiver agent with the DEAD files from the inventory.

The agent will:

1. Re-verify each file has no live references (final safety check)
2. Create _archive/ with mirrored directory structure
3. git mv each dead file into the archive
4. Clean up broken references in remaining files
5. Append to _archive/ARCHIVE_LOG.md

Archive in batches by directory, running tests between batches:

• Tests pass: commit with chore: archive stale files from <dir>
• Tests fail: restore that batch, log, skip, continue

After all batches: update phase "archive": "done".

Phase 5: Verify

1. Run the full test suite
2. If anything fails, report which archived file likely caused it and offer to restore: git mv _archive/<path> <path>
3. Print a final summary:

#### Codebase Simplify Complete

##### Simplified (N modules)
| Module | Changes | Commit |
|--------|---------|--------|
| src/dashboard | 12 fixes | abc1234 |

##### Archived (K files, ~M lines removed)
| File | Confidence | Reason |
|------|-----------|--------|
| src/old-widget.tsx | 92 | No imports, 120 days stale |

##### Skipped (J items)
| Item | Reason |
|------|--------|
| src/utils | Tests failed after simplification |

##### Impact
- Lines removed: ~M
- Files archived: K
- Active code simplified: N modules
- All tests passing: Yes/No

4. Delete simplify-progress.json.

Resume Behavior

When invoked and simplify-progress.json exists:

1. Read the progress file.
2. Find the first phase still marked pending or in-progress.
3. If a phase is in-progress, check git status:
   • Clean tree: treat as pending (session ended before committing)
   • Dirty tree: revert and treat as pending
4. Continue from that phase. No questions asked.

Configuration

Users can customize via simplify-progress.json or command arguments:

• stalenessWindow: Days since last modification to consider stale (default: 30)
• archiveDir: Where to put archived files (default: _archive/)
• autoArchive: Skip confirmation for files with confidence 90+ (default: false)
• excludePaths: Glob patterns to never archive (e.g., ["docs/**", "scripts/**"])

Important Notes

• The staleness-analyzer runs first and its inventory gates everything else. No simplification or archiving happens without the classification step.
• The code-simplifier ONLY touches FRESH files. It never modifies stale or dead code (that would be wasted effort).
• The stale-archiver uses git mv so full file history is preserved. Restoring an archived file is a single command.
• Each phase commits independently so progress is never lost.
• If context limits approach mid-phase, commit progress and update the progress file so the next session resumes cleanly.