| name | workflow-checkpoint-refactor |
| description | Multi-phase refactoring with checkpoint files that survive context limits. Use when refactoring spans 10+ files, needs phased rollout, or risks running out of context mid-session. |
| args | [--init|--continue|--status|--phase=N] |
| allowed-tools | Bash(git status *), Bash(git diff *), Bash(git log *), Bash(git add *), Bash(git commit *), Bash(npm run *), Bash(npx *), Bash(uv run *), Bash(cargo *), Read, Write, Edit, Grep, Glob, Task, TodoWrite |
| argument-hint | --init to create plan, --continue to resume, --status to check progress |
| created | "2026-02-08T00:00:00.000Z" |
| modified | "2026-06-21T00:00:00.000Z" |
| reviewed | "2026-02-14T00:00:00.000Z" |
/workflow:checkpoint-refactor
Multi-phase refactoring with persistent state that survives context limits and session boundaries.
When to Use This Skill
| Use this skill when... | Use direct refactoring instead when... |
|---|
| Refactoring spans 10+ files | Changing 1-5 files |
| Work will exceed context limits | Small, focused change |
| Need to resume across sessions | Single-session task |
| Multiple dependent phases | Independent file changes |
| Team coordination on large refactor | Solo quick fix |
Context
- Repo root: !
git rev-parse --show-toplevel
- Plan file exists: !
find . -maxdepth 1 -name REFACTOR_PLAN.md
- Git status: !
git status --porcelain
- Recent commits: !
git log --oneline --max-count=5
Parameters
--init: Create a new refactoring plan interactively--continue: Resume from the last completed phase--status: Show current plan progress--phase=N: Execute a specific phase
Plan File Format
The plan file (REFACTOR_PLAN.md) serves as persistent state. It is the loop's
compact state packet (.claude/rules/loop-integrity.md): a fresh session,
or a sub-agent with no memory of prior phases, must be able to re-enter from this
file alone. Every phase therefore carries not just what to do but what was
verified and what changed — without those, resuming across a context limit
silently redoes or undoes work.
# Refactor Plan: {description}
Created: {date}
Last updated: {date}
Base commit: {hash}
Exit condition: {the literal criterion that ends the whole refactor — e.g. "all phases done, full suite + tsc green on base"}
## Overview
{What is being refactored and why}
## Phase 1: {phase name}
- **Status**: done | in-progress | pending | needs-review
: file1.ts, file2.ts, file3.ts
: {what this phase does}
: {how to verify success — the phase's exit condition}
: {what the independent check returned — PASS/FAIL + the criterion it judged; filled in at the phase boundary}
: {what this phase actually touched, so a successor doesn't redo or undo it}
: {summary of changes made, filled in after completion}
: pending
: file4.ts, file5.ts
: {what this phase does}
: {how to verify success}
: {empty until verified}
: {empty until completed}
: {empty until completed}
...
