Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

workflow-checkpoint-refactor

/workflow-checkpoint-refactor

Prowadzi wielofazową refaktoryzację z plikami punktów kontrolnych, które przetrwają limity kontekstu, gdy zmiana obejmuje ponad 10 plików lub grozi wyczerpaniem kontekstu.

Repozytorium
claude-plugins ↗
Licencja
MIT
Ostatnia zmiana repozytorium
24.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 24.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi wielofazową refaktoryzację z plikami punktów kontrolnych, które przetrwają limity kontekstu, gdy zmiana obejmuje ponad 10 plików lub grozi wyczerpaniem kontekstu.

Argumenty

/workflow-checkpoint-refactor --init to create plan, --continue to resume, --status to check progress
Oryginalny opis (EN)

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.

Jak działa

  1. When to Use This Skill
  2. Context
  3. Parameters
  4. Plan File Format
  5. Execution
  6. Recovery Patterns
  7. Agentic Optimizations
  8. Quick Reference
  9. Related Skills
Sekcje z nagłówków SKILL.md, w oryginale · 195 linii, 1 258 słów
Podgląd SKILL.md
---
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-08
modified: 2026-09-23
reviewed: 2026-02-14
---

# /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*, *what changed*, and *what must come first* — and the plan names the
phase the last run chose next. Without those, resuming across a context limit
silently redoes or undoes work, or re-derives the order from the transcript.

```markdown
# 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"}
Next target: {the phase the last run chose to do next, and why — set before a run ends}

## Overview
{What is being refactored and why}

## Phase 1: {phase name}
- **Status**: done | in-progress | pending | needs-review
- **Files**: file1.ts, file2.ts, file3.ts
- **Description**: {what this phase does}
- **Ordering / preconditions**: {what must hold before this phase starts — e.g. "none (first phase)"; keep it to a line or two}
- **Acceptance criteria**: {how to verify success — the phase's exit condition}
- **Verifier result**: {what the independent check returned — PASS/FAIL + the criterion it judged; filled in at the phase boundary}
- **Changed since last run**: {what this phase actually touched, so a successor doesn't redo or undo it}
- **Result**: {summary of changes made, filled in after completion}

## Phase 2: {phase name}
- **Status**: pending
- **Files**: file4.ts, file5.ts
- **Description**: {what this phase does}
- **Ordering / preconditions**: {e.g. "after Phase 1 — uses its shared types"}
- **Acceptance criteria**: {how to verify success}
- **Verifier result**: {empty until verified}
- **Changed since last run**: {empty until completed}
- **Result**: {empty until completed}

...
```

## Execution

Execute this multi-phase refactoring workflow:

### Step 1: Initialize refactoring plan (--init mode)

If `--init` flag provided:

1. Analyze scope: Read files to be refactored, understand dependencies
2. Define phases where each:
   - Touches 3-7 files (bounded scope)
   - Has clear acceptance criteria (tests, type check)
   - Can be committed independently
   - Builds on previous phases
3. Write plan file: Create `REFACTOR_PLAN.md` at repo root
4. Record base commit: `git log --format='%H' -1`

**Phase ordering**: Shared utilities/types first, leaf components last, tests alongside implementation.

### Step 2: Resume existing refactor (--continue mode)

If `--continue` flag provided:

1. Read `REFACTOR_PLAN.md`
2. Take the plan's **Next target**; if it is empty, fall back to the first
   pending phase (status `pending` or `needs-review`)
3. Verify the phase's **Ordering / preconditions** hold (prior phases it names are
   `done`); if one does not, work the unmet precondition instead
4. Execute phase (go to Step 4)

### Step 3: Check progress (--status mode)

If `--status` flag provided:

1. Read `REFACTOR_PLAN.md`
2. Parse plan and display status table with phases, descriptions, statuses, file counts
3. Exit

### Step 4: Execute target phase (--phase=N or selected via Step 2)

For each phase:

1. Read context from plan file (current phase's details)
2. Read only the files listed for this phase
3. Implement changes according to phase description
4. Validate with appropriate tool (tsc, ty check, cargo check, or npm/pytest test)
5. If validation fails:
   - Fix errors if straightforward
   - If complex, mark phase as `needs-review` with error details
   - Commit partial work with `WIP:` prefix
6. If validation passes, **gate `done` on an independent verifier** when the
   acceptance criteria are a judgement (e.g. "the class is now single-purpose"),
   not a purely mechanical check (a green suite / clean `tsc` is already
   independent — a failing test does not care how hard you worked):
   - Dispatch a fresh `Task` sub-agent that reads **only** this phase's
     acceptance criteria and the resulting diff — not the worker's reasoning —
     and judges whether the criteria are met. The worker is biased toward
     declaring completion; the loop's stop condition must come from outside it
     (`.claude/rules/loop-integrity.md`, Pillar 1). When the criteria are about
     **behaviour** ("endpoint returns X", "the bug no longer reproduces"),
     delegate this to `agent-patterns-plugin:execution-grounded-review`, which
     runs the suite first and grounds each criterion in execution evidence
     rather than appearance.
   - Record the verdict in the phase's **Verifier result** field (PASS/FAIL +
     the criterion judged).
   - If the verifier returns FAIL, leave status `in-progress`/`needs-review`
     and address the gap before marking `done`.
7. Once verified, update the plan file: set status to `done`, fill **Verifier
   result**, **Changed since last run**, and **Result**, set the plan's
   **Next target**, then commit:
   `git add -u && git commit -m "refactor phase N: {description}"`
8. If more phases remain, proceed to next phase or suggest `--continue`

### Step 5: Sub-agent delegation (for large phases)

For phases with 7+ files, delegate to Task sub-agent with:
- File list to modify
- Phase description and acceptance criteria
- Instructions: run validation, update plan file, stage/commit changes
- If validation fails: mark phase as `needs-review` with error details

## Recovery Patterns

| Situation | Action |
|-----------|--------|
| Context limit hit mid-phase | Start new session, run `--continue` |
| Phase marked needs-review | Read plan for details, fix issues, run `--phase=N` |
| Tests broken after a phase | Revert phase commit, investigate, re-execute |
| Plan needs adjustment | Edit REFACTOR_PLAN.md directly, update phases |
| Base branch moved | Rebase onto new base, re-validate completed phases |

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Check plan exists | `test -f REFACTOR_PLAN.md && echo "exists"` |
| Quick typecheck | `npx tsc --noEmit --pretty 2>&1 \| head -20` |
| Quick test | `npm test -- --bail=1 2>&1 \| tail -20` |
| Phase commit | `git commit -m "refactor phase N: description"` |
| Verify working state | `npx tsc --noEmit && npm test -- --bail=1` |
| Show plan phases | `grep "^## Phase" REFACTOR_PLAN.md` |
| Show phase status | `grep -A1 "^## Phase" REFACTOR_PLAN.md \| grep Status` |

## Quick Reference

| Operation | Command |
|-----------|---------|
| Init new refactor | `/workflow:checkpoint-refactor --init` |
| Check progress | `/workflow:checkpoint-refactor --status` |
| Resume work | `/workflow:checkpoint-refactor --continue` |
| Run specific phase | `/workflow:checkpoint-refactor --phase=3` |
| Manual plan edit | Edit `REFACTOR_PLAN.md` directly |

## Related Skills

- [code-review-checklist](../../../code-quality-plugin/skills/code-review-checklist/SKILL.md) - Review refactored code
- [code-refactor](../../../code-quality-plugin/skills/code-refactor/SKILL.md) - Refactoring techniques
- [adversarial-review](../../../agent-patterns-plugin/skills/adversarial-review/SKILL.md) - The isolated verifier a judgement-based phase gate delegates to
- [execution-grounded-review](../../../agent-patterns-plugin/skills/execution-grounded-review/SKILL.md) - The execution-grounded verifier for behaviour-based phase acceptance criteria
- `.claude/rules/loop-integrity.md` - Why the plan file is a state packet and why `done` is judged independently

Wersje

W bazie nie ma innych skilli o nazwie workflow-checkpoint-refactor.

Migawka bazy z 13.11.2026 · wersja paczki f35b5f7fd4b3 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90refactor
    Przeprowadza refaktoryzację z zachowaniem działania: punkt kontrolny, wydzielanie, testy i audyt zmian.
  • 86refactoring
    Pomaga refaktoryzować kod, gdy użytkownik wyraźnie prosi o refaktoryzację.
  • 96code-refactoring-context-restore
    Prawdopodobnie wspiera refaktoryzację kodu przez odtwarzanie kontekstu pracy, na podstawie nazwy.
  • 100checkpoint
    Zapisuje i zmienia stan workflow: inicjuje go, aktualizuje pola, przechodzi między fazami i tworzy ustrukturyzowane przekazanie przed wyczerpaniem kontekstu, zapisując stan w magazynie zdarzeń.
  • 90thoughtbox:refactor
    Prowadzi refaktoryzację z kontrolą zakresu plików, zgodami na jego rozszerzenie i licznikiem kruchości kodu.
  • 100refactor-team
    Prowadzi zespołową refaktoryzację kodu z analizą i zmianami zatwierdzanymi przez użytkownika.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.