# Refactoring

> Use when refactoring code, reorganizing modules, renaming types, deleting old paths, or migrating architecture. MUST read before any structural code change. Prevents incomplete refactoring that silently breaks downstream consumers.

- Skill: `tomevault-io/refactoring-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/refactoring-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/refactoring-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/refactoring-3

---


# Refactoring

Prove the new path inherits every contract from the old path before deleting it. If you cannot prove it, do not delete.

## Past Incidents

| Date | What happened | Why | Impact |
|------|--------------|-----|--------|
| 2/14 | externalState handler became a throw stub | New path was not implemented when old path was deleted | completionType (now `runner.verdict.type`) functionality lost |
| 2/14 | Deno cache served stale version | --reload not run, so fixed code was not picked up | Fix existed but bug reproduced |
| 2/13 | V1 handler exports removed | Adapter not created, old interface compatibility lost | import errors |
| 1/18 | Legacy completionType aliases removed (now `runner.verdict.type`) | Old agent.json configs broken with no migration grace period | Config file incompatibility |
| 1/9 | Dead code left behind (cli.ts, runner/cli.ts) | Old entry points not cleaned up after migration | Multiple paths caused confusion |

## Failure Patterns

| Pattern | Why it breaks | Prevention |
|---------|--------------|------------|
| Old path deleted + new path incomplete | Contract breaks in the intermediate state | List all contracts in Before/After table before deleting |
| Parameter gate declaration missing | Filter blocks undeclared arguments silently | Verify declarations at every gate from entry to consumer |
| Build cache inconsistency | Cache serves old module instead of updated one | Run --reload or clear cache after every change |
| Dead code left behind | Produces false positives in grep/search, causes confusion | Delete superseded code in the same PR |
| Documentation not updated | Users cannot discover preconditions | Grep docs for changed names and update all references |

---

## Phase 1: Inventory

Map everything being removed or changed before writing any code.

**1. Removal Inventory** — List what is being removed, who consumes it, and what parameters it receives.

```markdown
| Item | File | Consumers | Parameters |
|------|------|-----------|------------|
| createCompletionHandler | factory.ts:42 | builder.ts, runner.ts | args.issue, args.repo |
```

**2. Gateway Audit** — Trace every value from entry point to consumer, identifying filters and gates in between. Confirm the new path passes every parameter the old path consumed.

```
Entry (CLI) → Filter (run-agent.ts:196) → Runner → Factory → Handler
                 ↑ blocked if not declared in definition.parameters
```

**3. Consumer Audit** — Grep imports and call sites to identify every consumer. Determine the migration target for each. If any consumer has no migration target, deletion is not allowed.

## Phase 2: Contract & Verification Design

Define what contracts to preserve and how to prove preservation before writing any code.

**4. Before/After Table** — List each old-path behavior as a row and describe how the new path achieves it. Any row with an empty "After" column means the refactoring is not ready.

```markdown
| Behavior | Before | After | Verified |
|----------|--------|-------|----------|
| args.issue reaches handler | Direct path in createCompletionHandler | Registry + definition.parameters declaration | [ ] |
```

**5. Verification Design** — For each row in the Before/After table, decide what to verify, why, and how.

**What (what to protect)**: The input/output and error contracts that callers depend on. Boundary behavior, not implementation details.

**Why (why verify there)**: Past failures show that breakage occurs at boundaries, not at the point of change.

| Fragile boundary | Why it breaks | Example |
|-----------------|---------------|---------|
| Parameter reachability | Intermediate filter blocks undeclared args | --issue lost because definition.parameters lacked declaration |
| Interface compatibility | Old and new API method signatures differ | V2 refreshState/check vs V1 isComplete |
| Export continuity | Removing re-exports breaks downstream imports | V1 exports bulk deletion |
| Module resolution | Cache serves old version of the module | DENO_DIR split across two directories |

**How (how to choose the proof method)**: Match proof method to path complexity. Tests are a means of proof, not a goal.

| Path characteristic | Proof method |
|--------------------|-------------|
| Straight line, 1-2 hops | Code review is sufficient |
| Contains branches, filters, or async | Automated test on boundary input/output pairs |
| Depends on external state (cache, API) | E2E execution through the real environment |

## Phase 3: Execute

**6.** 1 commit = 1 concern. Separate into: add new path → migrate consumers → delete old path → update docs.

**7.** Every commit must pass `deno task ci`. If the intermediate state breaks, the commit granularity is too coarse.

**8.** Delete dead code in the same PR. "Cleanup later" never comes.

## Phase 4: Verify

**9. Cache clear** — On macOS, DENO_DIR can split across `~/.cache/deno` and `~/Library/Caches/deno`. Clear both.

```bash
deno cache --reload <entry-point>
```

**10. E2E parameter trace** — Confirm changed parameters reach the endpoint by running the actual command.

**11. Consumer grep** — Ensure zero remaining references. `grep -r "OldName" --include='*.ts' | grep -v test` must return empty.

**12. Docs grep** — Ensure zero stale references in docs. `grep -r "OldName" --include='*.md'` must return empty. See `docs-consistency` skill for full procedure.

---

## Anti-Patterns

| Bad | Good |
|-----|------|
| Delete old path, implement new path later | Make new path work first, then delete old |
| Assume "nobody uses this" without grep | Show evidence via consumer audit |
| Combine refactor and feature in one PR | Separate for bisectability |
| Fix the throw site | Trace where the parameter was lost |
| Skip cache clear after refactor | Always --reload after changes |

## Related Skills

| Skill | When to use together |
|-------|---------------------|
| `fix-checklist` | Root cause analysis before deciding what to refactor |
| `functional-testing` | Automated test design in Phase 2 |
| `docs-consistency` | Documentation updates in Phase 4 |
| `work-process` | Team delegation for large-scale refactors |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/tettuan) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->