workflow-checkpoint-refactor

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}

...