Auto-decomposition: how Codowave splits a 50-file refactor into 8 PRs

The fastest way to waste an AI coding agent is to give it one ticket that should have been six tickets. The model may still write decent code, but the pull request comes back too large to review and too risky to merge. A 50-file auth refactor can contain five good changes, two questionable ones, and one broken migration. At that point the whole PR usually sits until someone closes it.

We saw that pattern in early Codowave runs. Small issues landed. Oversized issues often died in review, even when most of the code was usable. The fix was not a bigger model prompt. The fix was to split the work before the agent started editing.

Auto-decomposition is Codowave's scope control layer. It reads a tracker ticket, estimates the size of the likely change, and turns large work into a queue of smaller sub-issues. Each sub-issue gets its own branch, its own tests, and its own PR.

The rule

Before Codowave writes code, it estimates the issue's scope. The estimate uses the issue text, the repo index, likely affected files, and a projected token budget. If the issue is below the limit, the agent works it as one PR. If the issue is above the limit, Codowave proposes smaller sub-issues that can ship one at a time.

An issue called Refactor the auth module might become this sequence:

1. Move password hashing into auth/hashing.ts.
2. Add tests around the existing session behavior.
3. Introduce the new session adapter behind the old API.
4. Update login and logout handlers to use the adapter.
5. Move shared error formatting into one helper.
6. Remove deprecated auth helpers after the callers move.
7. Update integration tests and docs.
8. Add a migration note for the old API.

That shape matters. A reviewer can merge the hashing extraction without also accepting the session migration. If step four is wrong, steps one through three can still land. If the whole thing needs to stop, the parent issue still shows exactly where the chain paused.

Why scope beats confidence

Autonomous agents do not fail only because they pick the wrong line of code. They fail because they change too much at once. The larger the PR, the harder it is for a human reviewer to separate useful work from accidental work.

Small PRs create better feedback. Review comments are narrower. Failed tests are easier to diagnose. Rollbacks are less dramatic. The agent also has less context to hold in memory, which leaves more budget for reasoning about the files that matter.

Our default ceiling is tuned so normal tickets stay as one issue. Bug fixes, copy changes, dependency bumps, and small feature work should not get split for the sake of process. The top slice of large work gets decomposed: framework upgrades, module refactors, data model migrations, and other tickets where one sentence hides a week of engineering.

How Codowave builds the split

The first pass is a scope estimator. It does not call the worker model. It reads the issue, checks symbol names and file names against the repo index, and returns likely files, rough change size, and estimated token use. It is allowed to be conservative. A false positive costs a planning step. A false negative can produce a PR nobody wants to review.

When the estimate is too large, a planner proposes the split. The planner gets the issue, the likely file list, dependency hints, and a strict output shape. It returns titles, summaries, file hints, and dependency order for each sub-issue. The planner does not write code.

The worker agent picks up the first sub-issue after you accept the plan. Each sub-issue moves through the normal Codowave loop: plan, edit, test, retry, open PR, hand off. The next sub-issue waits until the previous one is merged or skipped.

This separation keeps planning and coding from bleeding into each other. The planner decides where to cut. The worker stays inside one cut.

What you see in the product

In the dashboard, a large issue does not disappear into a long-running job. You see the proposed sub-issues before coding starts. You can rename them, drop one, change the order, or cancel the run.

The billing is visible too. Codowave plans charge per issue processed, with higher tiers including larger monthly allowances and unlimited usage on paid plans. If one broad request becomes eight sub-issues, it counts as eight issues. That is intentional. The cost should be visible before the agent spends compute and before a reviewer spends attention. See pricing for the current plan allowances.

That trade is usually worth making. Eight reviewable PRs beat one giant PR that blocks for a week. If the plan feels too expensive for the value of the work, you can delete the lower-priority sub-issues before they run.

Where it helps

Auto-decomposition works well when a ticket contains several related changes that can land in order. Refactors are the common case. So are framework upgrades, migration work, large cleanup passes, and feature work that touches backend, frontend, tests, and docs.

It also works well for teams that batch maintenance. A scanner might file one issue called Clean up stale React Query usage. The useful answer is rarely one PR across every stale callsite. The useful answer is a short queue grouped by route, package, or shared helper.

The important part is review shape. If a human engineer would naturally split the work into smaller commits or PRs, the agent should do the same before it starts.

Where it does not help

Some work is atomic. A one-file bug fix does not need decomposition. A global rename may touch many files but still be one logical operation. Splitting that kind of change can make it harder to reason about because half the repo is on one name and half is on another.

Design-heavy tickets are another weak spot. Make the homepage feel tighter can be decomposed mechanically, but the hard part is taste, not scope. Those issues need clearer acceptance criteria before an agent sees them.

The last weak spot is dependency between sub-issues. If step three cannot be tested until step seven lands, the split is wrong. Codowave's planner tries to avoid that, and we still expect humans to review the proposed chain before work starts.

The takeaway

Autonomous coding works best when the agent ships changes a reviewer can read in one sitting. Auto-decomposition makes that the default for large tracker tickets. It turns one risky request into a queue of smaller PRs, exposes the cost up front, and gives the team a clean stop point after every merge.

If you want to test it, pick one refactor that has been sitting in your backlog because it is too broad. File it as one issue. A good split should make the work look less impressive and more mergeable. That is the point. For a side-by-side run on real backlog issues, see the weekend with Codowave field report — and if you are still picking between agents, the Cursor / Devin / Sweep / Cline comparison puts each tool against the job it actually fits.