refactor-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

# Refactor Loop

> **Substrate note.** The production orchestrator is the **Workflow tool**
> (`${CLAUDE_PLUGIN_ROOT}/workflows/refactor-loop.js`): deterministic JS owns the loop, the gate and the
> stop, so the G7 and G10 hooks are unneeded there and only the G2 test-file lockbox remains. This prose
> skill is the **optional `--interactive` fallback** for step-by-step debugging — the same loop as prose
> the model executes, and less deterministic, because prose can drift. Prefer the Workflow path unless
> inspecting the loop by hand.

Act as the **orchestrator** of a gated refactoring loop — the cage — and own its control flow: the
test gate, the routing decisions, the stop predicate. Two subagents supply judgment (the brain):
`refactor-proposer` generates one candidate refactoring at a time, and `refactor-critic-correctness`
judges it. Keep the gate decision from every subagent, and let no subagent declare the loop done.

This is structure-only work. Behavior is preserved absolutely, and only the external test
suite certifies that — never a subagent's say-so.

The standards are `${CLAUDE_PLUGIN_ROOT}/rules/refactoring.md`, `${CLAUDE_PLUGIN_ROOT}/rules/coding.md`,
and the named refactorings in `${CLAUDE_PLUGIN_ROOT}/rules/refactoring-catalog.md`. The frozen rubric the
critic applies is `${CLAUDE_PLUGIN_ROOT}/refactor/rubric.md`.

## Relationship to /phil:refactor

`/phil:refactor` works a flat `.refactoring-backlog.md` interactively, committing per item.
This loop is different: it runs a closed proposer/critic/gate cycle against a **separate**
DAG ledger, `.refactor-loop-ledger.md` in the project root. The two never share a file and
never collide. Both detect the test runner the same way — see
`${CLAUDE_PLUGIN_ROOT}/skills/shared/test-runner-detection.md`.

## The argument

`$ARGUMENTS` may contain `--max-iterations N` to override the default of **10**. It may also
name a `target_scope` (a file, directory, or `--changes`). With no argument, the scope is
the code files in `git diff HEAD~1 --name-only` and `max_iterations` is 10. Resolve the scope once,
at INIT; it stays fixed for the run, because each green refactor moves HEAD.

---

## The state machine

Run these states in order. Each transition is a deterministic decision you make — not a
subagent's. Track `iter`, starting at 0.

```
INIT ─►PROPOSE ─►REVIEW ─►[GUARD]─►APPLY ─►TEST ──green──►LEDGER ─┐
          ▲         │ reject/≥major │              │              │
          │         └──────────────┘              red             │
          │            back-prompt                 ▼              │
          │            the proposer             REVERT ─► LEDGER ──┤
          │                                  (invalidate deps)     │
          └──────────────── strong-left, iter<max ─────────────────┤
                                                                    │
                              no-actionable / none pending ► DONE ◄──┘
                              iter≥max ────────────────────► HALT (report, don't fake)
```

### INIT  (cage)

1. Work with the session's working directory at the project root, where the hooks look for the
   ledger. If an existing ledger was left `active-run: true` from an interrupted run, say so and clear
   the flag first.
2. Run `git status --porcelain -- . ':!.refactor-loop-ledger.md' ':!.refactoring-backlog.md'` — the
   ledger and a seeding review's backlog are the loop's own uncommitted files. If it prints anything, stop and ask the user to commit or stash
   (`git stash push -u -- . ':!.refactor-loop-ledger.md'`) first: REVERT discards uncommitted edits in
   the files it restores. A diff an interrupted run left applied was never gated, so suggest stashing
   it rather than committing it.
3. Detect the test runner using `${CLAUDE_PLUGIN_ROOT}/skills/shared/test-runner-detection.md`.
4. Run the **baseline suite** as a discrete Bash call and read `$?` directly. Guard **G1**:
   if the exit code is non-zero, the suite is red — go straight to **HALT**. Never refactor
   on a red suite (`${CLAUDE_PLUGIN_ROOT}/rules/refactoring.md` §Safety). This is a `stop`.
5. Create or load `.refactor-loop-ledger.md` in the project root (format below). Write its
   header: `runner`, `baseline: green @ <git-sha>`, `iter: 0 / max <N>`, and the `pinned:`
   list. Write the active-run marker, which arms the G2 hook for this run.
6. Snapshot the pinned constraints into the ledger header — the durable, compaction-immune
   source (G7). Default pinned set: `preserve-public-api`, `no-test-file-writes`.
7. If the ledger has no nodes yet, gather candidate smells for the `target_scope`. You may
   run `/phil:review-code <scope>` to seed nodes, then convert into ledger nodes only items whose
   **Route** is `/phil:refactor` — a `report only` item changes behaviour, and a test-file item is
   one G2 refuses.
8. Set `iter = 0`. Proceed to PROPOSE. Increment `iter` on every return to PROPOSE, whatever the path
   back — G5, a G6 skip, the green or the red LEDGER — so G8 bounds them all.

### PROPOSE  (brain → cage)

1. **Guard G8 (every step):** if `iter ≥ max_iterations`, go to HALT-INCOMPLETE.
2. Re-assert the pinned constraints from the ledger header (**G7**) before invoking.
3. Invoke `refactor-proposer` via the Task/Agent tool. Pass it the curated state — and only
   that: `pinned_constraints[]`, `ledger_open_nodes[]` (status `pending` only — never pass
   reverted nodes or their invalidated dependents), `last_failure_evidence?`, `target_scope`.
   Do **not** pass prior proposer reasoning traces.
4. If the proposer returns `"no actionable proposal"`, go to **DONE** (T2).
5. **Guard G6 (schema):** if the manifest is not schema-valid JSON (§ proposer output),
   re-ask once. A second malformed return → log it, mark the node `skipped`, return to PROPOSE.
6. Otherwise proceed to REVIEW with the manifest.

### REVIEW  (brain → cage)

1. Invoke `refactor-critic-correctness` via the Task/Agent tool. Pass `{ diff, original_code,
   stated_intent (one line, NOT the proposer's trace), rubric_slice (Slice 1 of
   `${CLAUDE_PLUGIN_ROOT}/refactor/rubric.md`), pinned_constraints }`. Do **not** pass the proposer's
   reasoning — the critic must judge independently.
2. **Guard G6 (schema):** malformed verdict → re-ask once, then skip as above.
3. Proceed to GUARD with the verdict JSON.

### GUARD  (cage — pure boolean, no LLM)

Route on `verdict + severity + confidence`, threshold **θ = 0.6**:

- **G5:** if `verdict = reject`, OR any failing `per_criterion` item (`met: false`) has
  `severity ≥ major` and `confidence ≥ 0.6` → back-prompt the proposer (`llm_self_examine`): return to PROPOSE with
  the failing `per_criterion` items as `last_failure_evidence`.
- If `verdict ∈ {accept, revise}` with no blocking item → proceed to APPLY (T4).
- A `CANNOT_ASSESS` verdict is **not** an accept — back-prompt the proposer, as G5 does. An
  `accept` citing no `file:line` span is coerced to `CANNOT_ASSESS` first (rubric anti-flattery clause).
  A criterion whose `met` is `CANNOT_ASSESS` abstains and is not a failure.

### APPLY  (cage)

1. Confirm the tree is clean — `git status --porcelain -- . ':!.refactor-loop-ledger.md' ':!.refactoring-backlog.md'` prints

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin