/wbRefactor — Exhaustive Simulation ()
/wbRefactor is the surgeon. Its job is structural surgery on a specific file — change the shape of the code (decomposition, rename, extraction, pattern application) without changing what it does. The boundary that defines the command: behavior under tests stays identical; structure under reading changes.
Read this if you want to know why /wbRefactor has no flags, what counts as "behavior-preserving," and where refactor ends and /wbClean (cleanup) or /wbWork (feature change) begins.
1. Role & target
| Aspect | Behavior |
|---|---|
| Role | The Surgeon — structural transformation of one file or one tightly-coupled set of files. |
| Target | A specific file path; optionally a comma-separated set of files that will be transformed together atomically. |
| Cell scope | None directly. /wbRefactor does not mutate plan cells; the work it does should usually correspond to a plan row that /wbWork calls into. |
| Side effects allowed | Editing the targeted file(s); running existing tests to confirm behavior preservation. |
| Side effects forbidden | Adding new functionality; expanding scope to "while I'm here" cleanup; touching files outside the explicit target list. |
The "no scope creep" rule is what separates /wbRefactor from /wbClean. A surgeon doesn't decide mid-operation to also fix the patient's posture. If the refactor surfaces an unrelated mess, the agent names it (logs it as a candidate plan row) but does not act on it.
2. Argument resolution matrix
| Form | Example | What /wbRefactor does |
|---|---|---|
| Single file | Command: /wbRefactor core2/packages/wb-core/src/WBC.js | Surgical transformation of one file. Most common shape. |
| Comma-separated | Command: /wbRefactor src/WBC.js,src/WBCSlot.js | Atomic transformation of two tightly-coupled files. Both succeed or both revert. |
| Free-text intent | Command: /wbRefactor "extract the parser from WBC.js" | Refused. Refactor is target-required. Intent without a file target is a planning conversation, not a refactor. |
| Directory | Command: /wbRefactor core2/packages/wb-core/src/ | Refused. Refactor is file-level by design. |
The directory refusal is intentional. A "refactor everything in this directory" command is really a planning operation that should produce multiple plan rows, each refactoring a specific file. /wbRefactor keeps its scope narrow on purpose.
3. Flag matrix
/wbRefactor has no flags. The lack of flags is the design statement: every refactor is behavior-preserving on a specific target. There is no profile to choose, no severity to filter, no mode to toggle. The only question is "which file?" — and that's an argument, not a flag.
| What you might want | What to use instead |
|---|---|
| Refactor and fix lint warnings | /wbRefactor first, /wbClean after. Two commits, two clean intentions. |
| Refactor and add a feature | /wbWork --id="<row>" against a plan row that says so. Don't bundle. |
| Refactor that the tests don't cover | Ask the question first. /wbRefactor against untested code is dangerous; the agent will warn but proceed if explicitly told to. |
| Multi-file transformation | Comma-separated target. Atomic. |
4. Pipelines (the agent-native scenarios)
/wbRefactor core2/packages/wb-core/src/WBC.js> /wbRefactor core2/packages/wb-core/src/WBC.js💠 Pipeline The deferred WBC.js decomposition (when the architecture conversation has happened)
The active plan in this workspace defers row 3 (WBC.js decomposition) pending architectural discussion. After that discussion happens and a clear shape emerges, /wbRefactor is the right tool to execute it:
💠 Pipeline The atomic two-file rename
A function moved from one file to another, and both files need to be edited together to preserve the import graph:
💠 Pipeline The "refactor surfaces a separate problem" path
Mid-refactor, the agent notices something unrelated:
5. Edge cases & refusals
| Trigger | What /wbRefactor does |
|---|---|
| No target | Halt. ❌ /wbRefactor needs a file or comma-separated file list. |
| Directory target | Halt. ❌ Refactor is file-level. Use /wbPlan to break a directory into rows. |
| Free-text intent | Halt. ❌ Refactor needs a target file, not just intent. |
| Target file has no test coverage | Warn explicitly. Asks user to confirm proceeding. Auto-rollback isn't possible without a baseline. |
| Multi-file target where some files don't exist | Halt. Atomic refactor refuses partial targets. |
| Tests fail after refactor | Auto-revert all edits. Reports which test failed. The atomic guarantee is the safety. |
| User asks to add a feature mid-refactor | Refuse. Suggests /wbWork --id="<row>" against a plan row, not bundling into the refactor. |
| Refactor surfaces unrelated issues | Logs them as follow-ups with suggested next commands. Does not act. |
The pattern: /wbRefactor is behavior-preserving by contract. No flags, file-level only, atomic across multi-file targets, auto-reverts on test failure, refuses to expand scope. The only question it answers is "can the same behavior be expressed with a clearer structure?" Anything else is a different command.