audit-and-migrate

What this skill does

# Systematic Codebase Audit & Migration

A structured methodology for tackling codebases with accumulated technical debt. Works in three phases — **audit** (understand and freeze the problem), **migrate** (pay it down slice by slice with proof), then **closeout** (remove residue and prove the repo is actually ready to ship).

## Why This Methodology Exists

Agents without structure fail at four things during large refactors:

1. **Drift** — forgetting what's been done, redoing completed work, or leaving things half-finished across sessions. This wastes time and introduces conflicts.
2. **Vestigial code** — adding new implementations without deleting what they replace. The codebase grows when it should be shrinking.
3. **Intuition-driven confidence** — saying "this should work" instead of proving it. When an agent can't point to a deterministic check that passed, its confidence is unfounded.
4. **False finish** — stopping when the new path works even though temporary adapters, stale docs, orphaned dependencies, or release blockers remain.

Every rule in this methodology prevents one of these four failures. When a rule feels heavy, that's the justification.

---

## Session Protocol

**Do this at the start of every session.** This is what makes the methodology survive context compaction and session switches.

### Starting a Session

1. Check if control plane artifacts exist (look in `.claude/migration/` or wherever the project stores them):
   - `CHARTER.md`, `DECISIONS.md`, `SLICES.yaml`, `MAP.csv`, `RATCHETS.yaml`, `SHIP_CHECKLIST.md`
   - Latest `HANDOFF.md` if prior sessions have touched the migration
2. If they **don't exist** → you're starting fresh. Begin with Phase 1 (Audit).
3. If they **do exist** → read them in this order:
   a. `CHARTER.md` — re-absorb the mission and invariants
   b. `SHIP_CHECKLIST.md` — re-load the project-specific definition of "ready to ship"
   c. `DECISIONS.md` — understand what's been decided and why
   d. Latest `HANDOFF.md` — recover current status and blockers quickly
   e. All `in_progress` slices in `SLICES.yaml` — this is your current work
   f. Run the guard script to see current status

### Ending a Session

Write or update `HANDOFF.md` (or append to the most recent commit message if the handoff is small). Five parts, no exceptions:

1. **What changed** — files modified, slices advanced, decisions made
2. **What is now true** — new invariants, completed slices, updated budgets
3. **What remains** — incomplete slices, known risks, blocking issues
4. **What blocks shipping right now** — explicit blockers, or `None`
5. **Exact next steps** — the specific command or test sequence to run next

Example:
```markdown
## Handoff — 2026-03-01
### Changed
- Completed slice-003 (user routes auth migration)
- Ratchet budget for jwt.verify decreased from 8 → 5

### Now True
- All user route auth goes through withAuth() middleware
- Behavioral tests cover user routes at 100%

### Remains
- slice-004 (data routes) ready to start
- slice-005 (admin routes) blocked on Decision 4 re: webhook auth

### Shipping Blockers
- None

### Next Steps
1. Run `./guard.sh --status` to confirm baseline
2. Start slice-004: mark in_progress in SLICES.yaml
3. Write behavioral tests for src/api/posts.ts and src/api/comments.ts
```

This format survives context compaction. The next session (or a different agent) can pick up without information loss or having to guess whether the repo is actually releasable.

---

## Phase 1: Audit

The audit phase is about understanding the problem space before changing production code. Measuring first creates the foundation that makes migration safe, and defining the ship gate early prevents the common failure mode where the implementation lands but cleanup keeps spilling into follow-up runs.

### Step 1: Create the Charter

Create `CHARTER.md` using the template in [references/templates/CHARTER.md](references/templates/CHARTER.md). This defines:

- **Mission** — one sentence: what are you migrating and why
- **Critical workflows** — user-visible paths that must not regress
- **External surfaces** — public APIs, env vars, dashboards, webhooks, CLI entrypoints, data contracts, or automation hooks the migration might break outside the immediate repo
- **Invariants** — things that must remain true throughout (e.g., "all existing tests pass", "no user-facing behavior changes")
- **Non-goals** — things you're explicitly NOT doing (prevents scope creep)
- **Guardrails** — process rules
- **Ship gate** — the exact automated and manual evidence required before calling the migration done

The charter is the constitution. When in doubt about scope, check the charter.

### Step 2: Inventory the Problem Space

Catalog everything in the target domain — code, tests, scripts, docs, configuration, tooling, and dependencies. For each item, classify by leverage:

- **High** — keep and expand. Good code the migration builds on.
- **Medium** — keep but refactor. Structurally sound but needs updating.
- **Low** — replace. This is the debt you're paying down.

Be exhaustive. Anything missed here risks becoming vestigial code later. If an item is low leverage, record what will replace it or which slice will delete it.

### Step 2b: Capture Critical Workflows and Hotspots

Before designing slices, sweep for the parts of the system most likely to burn you later:

- **Critical workflows** — the user-facing paths that absolutely cannot regress
- **Known hotspots** — recent bug-fix churn, TODO/FIXME/HACK clusters, flaky tests, or fragile subsystems
- **Manual-only surfaces** — visual checks, hardware, or third-party UI flows automation cannot fully prove

These become your slice smoke tests, manual checks, and ship-gate inputs.

### Step 3: Measure Anti-Patterns

Use grep/ripgrep to count specific weak patterns. The goal is concrete numbers, not vibes.

For each pattern, record:
- The grep pattern used to find it
- The search scope used to find it
- The current count
- Why it's problematic

**Examples** (adapt to your codebase):
```
Pattern: source\.contains\(        Scope: test/          Count: 43    Problem: Tests code shape, not behavior
Pattern: Task\.sleep\(             Scope: test/          Count: 17    Problem: Non-deterministic timing
Pattern: struct Scenario           Scope: test/          Count: 22    Problem: Duplicated test scaffolding
Pattern: require\(.*/utils/old-    Scope: src/ docs/     Count: 8     Problem: Imports from deprecated module
```

### Step 4: Freeze with CI Ratchets

For each measured anti-pattern, create a ratchet that enforces a maximum budget equal to the current count. See [The CI Ratchet Pattern](#the-ci-ratchet-pattern) for the technique.

This is the most important step. Once ratchets are in place, debt can only decrease. No one — human or agent — can accidentally reintroduce eliminated patterns. Ratchets are only trustworthy if the query and search scope are explicit and the count measures matches, not just matching files.

Write these ratchets into `RATCHETS.yaml` using the template in [references/templates/RATCHETS.yaml](references/templates/RATCHETS.yaml). Do not let the guard script become the only place the budgets live.

### Step 5: Write the Audit Document

Create a comprehensive audit doc. Include:
- Method used (how you inventoried and measured)
- Current metrics (all anti-pattern counts)
- Leverage assessment (what's high/medium/low)
- Critical workflows and known hotspots
- Hard conclusions (what needs to change — be direct)
- Guardrails added (what CI checks are now in place)
- Ship criteria and manual-only verification surfaces
- Proposed slices (your initial plan for Phase 2)

### Step 5b: Produce Practical Reference Material

Alongside the control plane artifacts, produce domain-specific reference material that will accelerate the actual migration work:

- **Translation guide** — a lookup table mapping old patterns to their new equivalents (e.g., raw SQL queries → ORM calls, Redux p