Assistant task sizing for large codebases that stay mergeable

Why large assistant changes get stuck

A huge assistant-generated diff looks fast for about an hour. Then review starts, and everything slows down.

One reviewer has to inspect business logic, renamed files, test updates, config edits, and cleanup in the same pass. That is how details get missed. People lose the thread, leave partial comments, then ask for a second review because the first one never had a clear scope.

Task sizing sounds like planning overhead, but in a large codebase it often decides whether a branch moves or stalls. When one prompt produces a feature change, a refactor, and a dependency update together, nobody knows what actually caused the problem. If login breaks, was it the new validation rule, the moved auth service, or the package bump? The real issue is buried inside the mix.

Tests get messy for the same reason. One branch starts failing in five places, but those failures do not point to one obvious mistake. They pile up. A flaky test hides a real regression. A schema change breaks fixtures. A renamed helper knocks out half the suite. Now the team is debugging the branch itself, not the product.

Rollback is where big diffs hurt most. If one commit changes UI copy, session logic, database fields, and logging, you cannot safely undo only the broken part. Reverting the whole thing removes fixes you wanted to keep. Reverting piece by piece takes time, and teams under pressure rarely do that well.

A simple example makes the problem obvious. Say you ask the assistant to "modernize login." It updates the form, changes error handling, swaps token storage, adds analytics events, and cleans old auth code. That sounds efficient. In practice, it creates one branch with four separate ways to fail and no clean way back.

Small pull requests feel slower on day one. After that, they move faster because people can review them, test them, and undo them without guessing.

Find the smallest useful slice

Start with one result a user can notice. If the request is "improve onboarding," it is still too wide. If the request is "show company size on the signup form and save it," the team has something it can review, test, and merge without guesswork.

Most small slices should stay inside one layer of the stack. Keep data changes, API changes, and UI changes apart when you can. It feels slower at first, but it saves time later because each diff has one job. When a single assistant run touches the schema, business logic, endpoints, and screens at once, review turns into detective work.

A useful rule is simple: one reviewer should be able to read the whole diff in one sitting and still have enough focus left to ask smart questions. For many teams, that means a change that takes 20 to 30 minutes to review, not half a day. If the reviewer needs to open six files just to understand the goal, the slice is still too big.

Before you prompt the assistant, do a quick check. The slice should have one user-visible outcome, stay in one layer when possible, fit into a short review window, and have one sentence that defines done.

That last part matters more than people think. "Done" should not mean "most of it works." It should mean something concrete, like "users can edit their billing email and the old flow still works."

This is the same habit Oleg Sotnikov uses in AI-first engineering work: keep the unit of change narrow enough that the team can see what changed, test it fast, and back it out without drama. Small pull requests are not just tidy. They are easier to trust.

If a task still feels fuzzy, cut it again. The smallest useful slice is usually smaller than your first guess.

Split one big request into clear steps

A broad request sounds efficient, but it usually produces a messy diff. If the assistant changes the UI, backend, config, and tests in one pass, review slows down and rollback gets ugly.

Start with one sentence that states the end result. Keep it plain and specific: "Add magic-link login for selected users without breaking the current password flow." If that sentence is trying to hold two goals, split it before you touch the code.

Then make a quick map of what might change. Name the files, services, or folders that are likely to move. In a login update, that could include the auth API, login page, email sender, feature flag config, and test files. This step matters because it shows how wide the change can spread before the assistant writes a line.

After that, pull out the prep work. Many risky changes get much safer when you ship the setup first. Prep work often means a feature flag, an adapter layer, test fixtures, logging, or a small database field that nothing uses yet.

A clean order often looks like this:

1. Add the flag or config switch.
2. Add adapters, stubs, or small interfaces.
3. Add or update tests for the new path.
4. Implement the backend logic behind the flag.
5. Update the UI or remove the old path later.

There is nothing fancy here. The point is to keep early slices easy to review and easy to undo.

Say you ask for "upgrade login." The assistant may touch ten files at once. Ask for the first slice instead: "Add a feature flag and test scaffold for magic-link login. Do not change user-facing behavior." That prompt gives you a small pull request, a clear test plan, and a clean stopping point.

If the first slice merges cleanly, ask for the next one. Keep going until the full change is done. Small steps feel slower on day one, but they usually save time by day three.

Set review limits before the first prompt

Review limits work best when you set them before the assistant writes a single line. If the diff gets too big, people skim, miss edge cases, and delay the merge because they do not know where to focus.

Start with a rough line budget for one slice. For many teams, 100 to 300 changed lines is still readable. In risky areas like login, billing, permissions, or shared infrastructure, the safer number is often much lower. The exact number matters less than having a clear cap that tells the assistant when to stop.

A good slice should also solve one concern. A change that updates validation rules, refactors folder structure, and tweaks UI copy is really three reviews pretending to be one. Even if each part is small, the reviewer has to hold too much context in mind.

A simple review rule can include four limits:

• one concern per slice
• one line budget for code and config changes
• one named reviewer for code, one for tests, and one for product behavior
• one short change note attached to every draft

Those roles matter. A developer can say the code is readable and still miss that the flow feels wrong. A product person can catch a broken screen state in two minutes. A tester can spot missing coverage even when the code looks clean.

Ask the assistant for a short change note every time. Keep it plain: what changed, what did not change, how to test it, and how to roll it back. That note saves time because reviewers do not have to reverse engineer the intent from the diff.

This is how small pull requests stay mergeable. The assistant gets a fence, reviewers get a clear job, and rollback gets easier because each slice has a narrow blast radius. If a change fails, you can revert one small step instead of backing out a week of mixed edits.

Tie each slice to one test plan

A slice is only small enough if you can prove it works with one short test plan. If you need a full regression run to feel safe, the slice is still too big.

Start with one main test. That test should answer the only question that matters for that slice. If the slice changes password reset email text, the main test is not the whole auth suite. It is one test that proves the right email goes out with the right token.

Add one smoke check for the user path around it. Keep it simple: a user requests a reset, gets the email, opens the link, and reaches the reset screen. That catches the obvious break without dragging in every edge case.

A practical pattern

Use the same order every time:

• pick one main test that proves the slice works
• add one smoke check for the user path
• keep fixtures and test data limited to that path
• run fast checks on each change
• leave slow suites for later batches or nightly runs

Test data often makes a small change feel bigger than it is. If one slice needs three new fixtures, five roles, and a new seed script, stop and cut the work again. A narrow slice should touch the smallest amount of setup needed to prove the behavior changed.

Run fast checks first because they give you a quick yes or no. Unit tests, one integration test, and one smoke path usually tell you enough to review the code with confidence. Broader suites still matter, but they do a different job. They protect the branch over time, not each tiny step.

This helps a lot in large codebases. The assistant can generate mergeable changes when each piece has one clear proof. Reviewers know what to inspect, CI stays fast, and rollback stays simple because each slice maps to one behavior instead of ten.

Make rollback easy before you merge

A change is only mergeable if you can undo it in minutes. Small diffs lose their value fast if one bad merge still forces a long recovery.

Put risky behavior behind a flag when you can. Merge the code with the flag off, test it with production-like traffic, then turn it on for a small group first. If something breaks, switch the flag off instead of rushing through a late-night revert.

Keep the old path and the new path side by side for a short window. That sounds messy, but it is often the cleaner choice. A week of duplicate logic is cheaper than an outage caused by removing the old path too early.

Database work needs extra care. Avoid schema changes that you cannot reverse in one step. Renaming a column, dropping a table, or changing data in place can trap you. A safer pattern is additive change first: add the new column, write to both places, read from the old one until the new path proves stable, then clean up later.

Before you merge, write the undo step in plain language and keep it short:

• turn off flag new_billing_flow
• revert commit abc123
• run the previous container image
• stop the background worker added in this change

If you cannot write a clear undo plan, the slice is still too big.

Save cleanup for a later pull request. Remove dead code, old flags, and extra writes only after the new path has stayed stable for a while. Teams often rush this because the old code looks ugly. Ugly code for three days is fine. A rushed cleanup that blocks rollback is not.

A good rule here is simple: every merged slice should have one owner, one test plan, and one rollback note. That keeps review faster and mistakes small enough to fix without panic.

A simple example from a login update

Say your app still accepts a legacy username field, but the new API wants email and password. If you ask the assistant to "migrate login," it may touch forms, validators, API calls, analytics, error messages, and user settings in one shot. That looks productive at first, then turns into a hard review and a risky merge.

A safer first slice is a small helper that can read both shapes. It checks the old login fields and the new ones, then returns one clean format for the rest of the code. Nothing else changes yet. Review stays simple because the team can look at one file and one job.

Before the helper goes live, lock in the current behavior with tests. Add tests for successful login, wrong password, empty fields, and any old edge case you still support. These tests do not improve the feature yet. They stop the assistant from "cleaning up" behavior that users still rely on.

After that, move one screen to the helper. Pick the least risky screen first, often the main web login page. Leave mobile, admin, and password reset alone for now. If something breaks, you know where to look, and rollback means one small revert instead of a full rewrite.

Then put the new path behind a flag and turn it on for a small group first. That might be internal staff, test accounts, or 5 percent of users. Watch login failures, support tickets, and odd drops in completion rate. Quiet logs matter more than a clean diff.

Only remove the old code after the new path runs without noise for a while. Teams often delete the fallback too early because the duplicate logic feels messy. Messy is fine for a short time. Broken login is not.

That whole update may still take five pull requests. Good. Each one is easy to review, easy to test, and easy to undo.

Mistakes that make slices too big

Most oversized assistant changes start as a normal request, then grow through a few extra asks. One feature becomes a feature plus a refactor plus cleanup. That is usually where task sizing breaks down. The change still sounds related, but it no longer fits one review, one test run, or one easy rollback.

Mixing refactors with feature work causes trouble fast. If the assistant updates login rules and also rewrites shared auth helpers, reviewers cannot tell which part changed behavior and which part just moved code around. Keep the feature change separate. Put the refactor in its own pull request, even if that feels slower.

Renaming files while changing behavior creates the same mess. A diff that moves files, fixes imports, and edits logic at the same time is harder to read and much harder to undo. When something breaks, you want a small revert. You do not want to sort through file moves late at night.

Asking for UI, API, and database changes in one prompt sounds efficient, but it creates a chain of failures. A small schema mistake can block the whole branch. A better split is one layer at a time, with each slice able to build, pass tests, and merge on its own.

Bundling cleanup into the first commit also makes review worse. Dead code removal, naming fixes, comment edits, and lint-only changes add noise. They hide the real change. Unless cleanup is required for the feature to work, save it for later.

Skipping rollback planning because the code looks simple is another common mistake. Simple changes still break sessions, forms, or old clients. Decide how you would undo the change before you merge it. If rollback needs custom data repair or three follow-up commits, the slice is too big.

A slice is probably too big when reviewers need a long call to understand it, the test plan checks several unrelated outcomes, the pull request mixes renames and cleanup with behavior changes, one database failure blocks the UI work, or rollback means more than a quick revert or feature toggle.

Teams that stay disciplined here ship more mergeable changes. They also spend less time arguing in review because each pull request answers one question instead of five.

Quick checks before you run the assistant

A good slice feels almost boring. One person can read it, run the tests, and decide "yes" or "no" without opening ten files to guess what changed.

Start with the review window. If a careful reviewer will need more than about 30 minutes, the request is too big. That usually means the assistant is touching too many files, mixing refactors with behavior changes, or fixing old messes at the same time.

A quick gut check helps:

• you can explain the change in one plain sentence
• the tests answer one question, not three
• you can undo the change with one revert
• any extra cleanup can wait for a later pull request

That one-sentence rule is stricter than it sounds. "Update login" is too broad. "Lock the account after five failed login attempts" is small enough to review. When the sentence needs "and" more than once, split it.

Tests should point at one behavior. If the change needs database updates, UI tweaks, API edits, and a migration test, you probably bundled several slices together. Small pull requests work because reviewers can match the code to one expected result.

Rollback is the other hard check. Ask what happens if production breaks an hour after merge. Can you revert the whole thing cleanly, or will you need a second patch to clean up half-finished schema changes, flags, or renamed helpers? If rollback is messy, the slice is too wide.

Cleanup is where teams quietly make a mess. The assistant updates a feature, then also renames old variables, moves files, and reformats unrelated code "while it is there." That makes review slower and rollback harder. Leave that work for later unless the change cannot ship without it.

Once a change is easy to explain, easy to test, and easy to undo, it is usually small enough to merge.

Next steps for your team

Pick one active project this week and use it as the test case. Do not start with the biggest mess in the repo. Pick a task that matters, but that your team can finish in a few days, then reslice it before anyone opens the assistant.

A short team rule beats a long process document. Keep it brief enough that people will actually use it during planning and review:

• one slice changes one small behavior, one area of code, or one clear refactor
• one slice gets one test plan before generation starts
• one slice has a rollback note that fits in a few lines
• if a reviewer cannot read it in one sitting, split it again

Write that rule down where your team already works. If people need a meeting to remember it, the rule is too long.

Then track merged change size for two weeks. Keep it simple. Count files changed, rough lines touched, review time, failed checks, and whether anyone had to revert or patch the change after merge. You do not need perfect data. You need enough to spot the point where work stops feeling safe.

Most teams learn one thing quickly: the changes that merge cleanly are usually boring to review. That is good. Boring pull requests are easier to test, easier to discuss, and much cheaper to undo.

If your team wants help setting these rules, Oleg Sotnikov shares this kind of practical Fractional CTO guidance through oleg.is. His work stays close to real delivery: review limits, test gates, rollback habits, and AI-first engineering practices that fit startup teams without turning into paperwork.

That is the habit worth building now: smaller requests, clearer tests, and easier reversions, repeated every week until it feels normal.