# Refactor Loop

> Characterization-test-first refactor loop. Generates Playwright/Vitest baseline tests capturing current behavior, commits them, then iterates refactor until tests stay green. Distinct from tdd-fix (bug-fix-first) — this is refactor-first. Triggers "/refactor-loop", "characterization tests", "safe refactor", "refactor with tests first".

- **Type:** Skill
- **Install:** `agentstack add skill-ao92265-claude-code-playbook-refactor-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ao92265](https://agentstack.voostack.com/s/ao92265)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ao92265](https://github.com/ao92265)
- **Source:** https://github.com/ao92265/claude-code-playbook/tree/main/skills/refactor-loop

## Install

```sh
agentstack add skill-ao92265-claude-code-playbook-refactor-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Refactor Loop — Test-Driven Safe Refactor

For *refactors* (no behavior change). Generates a behavioral safety net BEFORE touching code, then iterates the refactor until the net still holds.

## When to invoke

- Renaming/restructuring without semantic change
- Splitting a god component, extracting hook/util, deduping logic
- Migrating styles/theme without altering rendered output
- Library/version upgrade in a contained module

## When NOT to invoke

- Bug fix → use `tdd-fix`
- Feature add → use `dev-story` or normal flow
- Mechanical rename across files where existing tests already cover it

## Workflow

### Step 1 — Identify target + capture surface

Ask user (if not stated) for:
- Target file/dir
- Public surface to preserve: rendered output, network calls, exposed API, side effects

### Step 2 — Write characterization tests

Generate tests that PIN current behavior:

- **React component:** Playwright snapshot of rendered DOM in 2–3 prop states + assertion on emitted network calls
- **Pure function:** Vitest cases for every observed input → output pair from existing usage (grep callers)
- **Service/class:** Spec covering each public method's happy path + error paths

Tests MUST run green against unchanged code. If they fail on unchanged code → tests are wrong, fix them before continuing.

### Step 3 — Baseline commit

```bash
git checkout -b test/-baseline
git add 
git commit -m "test(baseline): characterization tests for  before refactor"
```

### Step 4 — Iterate refactor

Loop, max 20 iterations:

1. Make one small refactor increment
2. Run full suite: `tsc -b && npm test && npm run lint`
3. Green → commit `refactor: ` and continue
4. Red → diagnose ROOT CAUSE (not symptom):
   - Was behavior actually changed? → revert + rethink
   - Was baseline test brittle (timing, ordering)? → harden test in separate commit, then continue
5. Cap at 20 iterations. If goal not reached, surface to user with diff summary.

### Step 5 — Final diff report

```
Refactor: 
Baseline tests: 
Iterations: /20
Net diff: , +/-
Behavior delta: NONE (all baseline tests passing)
```

## Hard Rules

- NEVER skip the baseline test step. "I'll just be careful" is how regressions ship.
- Baseline tests committed in their OWN branch/commit before any refactor commit. Reviewable separately.
- Root-cause failures, never symptom-patch tests to make them pass.
- `tsc -b` (NOT `--noEmit`) — CI parity.
- If iteration cap hit: surface partial progress, do not silently push half-finished work.

## Subagent routing

- `executor` (sonnet) — write tests + refactor increments
- `verifier` (sonnet) — run suites + parse failures
- Escalate to `opus` only after 2 sonnet root-cause attempts on same failure.

## Triggers

`/refactor-loop`, "characterization tests", "safe refactor", "refactor with tests first", "lock in behavior before refactor"

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ao92265](https://github.com/ao92265)
- **Source:** [ao92265/claude-code-playbook](https://github.com/ao92265/claude-code-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ao92265-claude-code-playbook-refactor-loop
- Seller: https://agentstack.voostack.com/s/ao92265
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.