Refactor a tangled module
Carve a sprawling refactor into scoped diffs you can actually review.
Who this is for.
You are looking at a module that has grown into a load-bearing mess — circular helpers, three flavours of the same util, a god class everyone is afraid to touch. You want to break the work down into focused subtasks, run them in isolated worktrees, and review one tight diff at a time instead of one branch that touches forty files.
The workflow in 4 steps.
Draft the carve-out as a project definition
Open the project in Watchfire and write the refactor plan into `project.yaml` — the seams you want to introduce, the modules to split, the public API that must not change. The definition becomes the steady context every subtask inherits, so the agent stops over and over with the same intent.
Create one task per seam
Add a task YAML per slice: extract the helper, move the type, swap the call sites. Keep each task's `prompt` and `acceptance_criteria` narrow enough that a single diff can close it. If a slice grows past 200 lines on paper, split it before you start.
Let Watchfire run them in isolated worktrees
Hit start on the ready tasks (or flip Wildfire on for the whole queue). Each one runs in its own `watchfire/<n>` worktree on a dedicated branch, so a half-finished extraction in task #2 never poisons task #3. Failures stay scoped — only the offending subtask needs a rerun.
Review diffs one slice at a time
When a task lands, you get a tight reviewable branch with the task definition right next to the diff. Merge the ones that pass review immediately and send the messy ones back as a new task with sharper acceptance criteria — without unwinding everything else.
A real task you can copy.
Drop this into .watchfire/tasks/<n>.yaml, tweak it to your repo, and start it from the TUI or GUI.
task_id: rfctr001
task_number: 12
title: "Extract pricing helpers out of orders.ts into lib/pricing.ts"
prompt: |
`services/orders.ts` has grown to 1.4k lines and
mixes order lifecycle with pricing math. Extract
every pricing helper (anything that touches
`Money`, discounts, tax, or rounding) into a new
`lib/pricing.ts` module.
Keep the public surface of `services/orders.ts`
identical — callers must not need to change. Move
the helpers, re-export the ones that are
consumed externally from `services/orders.ts`
for now, and update internal calls to import
from `lib/pricing.ts` directly.
Out of scope:
- Renaming any helper.
- Touching the database layer.
- Changes outside `services/orders.ts`,
`lib/pricing.ts`, and their existing tests.
acceptance_criteria: |
- `lib/pricing.ts` exists and exports every
helper that used to live inline in
`services/orders.ts`.
- `services/orders.ts` no longer defines any
pricing math directly.
- `npm run test` and `npm run lint` pass.
- `git diff main -- services/orders.ts` only
shows imports and re-exports — no behaviour
changes.
status: ready
More starters in the task template library.
Why Watchfire makes this faster.
- Per-task git worktrees mean an aborted extraction can't leak dirty state into the next slice — you just restart the one task that failed.
- Acceptance criteria force you to declare the public API contract up front, so the agent can't quietly broaden the refactor while you're not looking.
- Wildfire mode keeps the queue moving on its own, so an eight-step refactor finishes overnight instead of stretching across a week of pair-driving the CLI.
- Every subtask lands on its own `watchfire/<n>` branch, so review and merge can happen incrementally — no one-shot mega-PR.
- The transcript per task is preserved, so when a reviewer asks 'why did you do it this way?' you have the prompt, the acceptance criteria, and the agent's reasoning side by side.
Keep reading.
Related use cases.
Drive a migration or codemod in parallel
Slice a framework upgrade per package and run them concurrently.
Read the playbook
Backfill tests on an under-covered module
Pin the coverage bar in acceptance criteria — and make the agent earn it.
Read the playbook
Hand a branch the PR description it deserves
Point an agent at a branch you already have — get a real PR write-up.
Read the playbook
Get started with Watchfire
Install in seconds. Define tasks. Let agents ship code for you.
Download for macOSAvailable for macOS, Linux, and Windows
# Install via Homebrew (macOS)brew tap watchfire-io/tapbrew install --cask watchfire-io/tap/watchfire# Set up your project and gowatchfire initwatchfire task add "Build the login page"watchfire start --allIncludes GUI, CLI, and daemon. Also available via Homebrew.