On this page5
Two co-founders talking through a plan on a rooftop at dusk
Make a refactor or ship decision by comparing the value of shipping now with the delivery risk and delay cost of changing code first. Refactor when evidence shows the current design makes this feature unsafe or costly to maintain; otherwise ship within clear limits and name what would make you revisit the choice.
What you’ll learn
- What is at stake in a refactor or ship decision
- How to compare shipping now with refactoring first
- Which evidence matters before you choose
- What signals should change your decision
- How to record the choice and its limits
What belongs in a refactor or ship decision?
Keep the decision narrow: should this feature ship on the current design, or should code change first? Name the feature and the user need it serves. A general argument about whether the codebase is clean enough will not help the team make this choice.
Separate a known defect from a concern about future maintenance. A defect can be reproduced or tied to a failed check. A maintenance concern may be real, but it needs a specific path from the current design to a problem for this feature.
Then state the cost of delay in terms your team can check. It might be a missed customer commitment, a blocked launch, or another piece of work that cannot start. Be equally specific about the risk of shipping: what could fail, who would be affected, and how you would notice?
Draw a boundary around the work. Name what code can change, what remains out of scope, and who can approve a change to that boundary. A definition of done for AI work can help make the finish line clear.
Tip: Write the decision as one sentence about this feature, not as a general verdict on the codebase.
What are you choosing between?
Make the options comparable. Shipping now should mean the smallest safe scope, not shipping without checks. Refactoring first should name the part of the design that changes and a point where the team stops and reviews. A broad rewrite is not the only way to reduce risk.
Compare each option against the same questions: what user value arrives, what delivery risk remains, what delay costs, and how easy it is to reverse course. Also name which unknowns each option could resolve. A refactor may reveal how a dependency behaves, but it can also leave the feature untested for longer.
| Choice | What ships or changes | Risk to check | Evidence to revisit |
|---|---|---|---|
| Ship within limits | The feature in a reduced, bounded scope | A known failure path or missing check | Defects, user impact, or failed acceptance criteria |
| Refactor first | A named code path, ending at a review point | Work expands or does not reduce the stated risk | A completed check against the feature criteria |
The table is a decision aid, not a scorecard. Do not add up unlike costs into a single number unless the team has a defensible way to compare them. For a larger choice, simulate business decisions before committing to work that may be hard to undo.
A person setting up a first desk with a laptop and a notebook
What evidence should change your choice?
Start with evidence tied to the feature. Can the team reproduce a defect? Does an acceptance check fail? Does the proposed change touch a code path this feature depends on? These questions help distinguish delivery risk from a preference for cleaner code.
Compare the refactor with the acceptance criteria. If changing the code does not make a failed criterion pass, be clear about what risk it addresses instead. Ask what evidence would show that shipping within limits is unsafe, and who can gather it. If nobody can name a test, observation, or failure that would settle the concern, record it as an open question.
A useful check is to write the smallest experiment that could change the choice. That might be a focused test, a code review of the relevant path, or a reduced release scope. Brainis says your acceptance criteria can become Verify checks, authored once, composed into libraries, and enforced per domain. Its deliverables arrive as reviewable diffs with Verify findings on exact lines before they count as done. See Verify for that product workflow.
Example: A fictional small company is preparing a billing change. One engineer worries that an old calculation path may mishandle a rare adjustment, but no one has reproduced the issue. The team writes a test for that adjustment and checks the path the feature will use. If the test fails, they pause and change that path; if it passes, they consider a limited release and watch for the same failure. The concern prompts a check, but it does not by itself prove a refactor is required.
Important: Treat an untested concern as an open question, not as proof that a refactor is required.
What signals should make you reverse the decision?
Set reversal signals before work starts. For shipping, name the defect, quality failure, or dependency change that would pause the release or narrow its scope. For refactoring, say what must be true before the change is complete, and what would make the team stop rather than keep expanding it.
Name who can approve a scope change or pause. That person should have the authority to act, and the team should be able to review the reason afterward. A new test failure is a new signal. Wanting a tidier design after the team agreed on a boundary is a change of preference. Record which one has occurred.
Brainis says every consequential action is governed by an authority contract and is auditable. Its missions carry pre-declared gates for burn, quality, drift, and deadline, and abort blamelessly when a gate trips. Those gates make a stop or go-around reviewable rather than a surprise. The guide to abort conditions for projects can help you define the signals before work begins.
A gate is useful only if the team can observe it and knows what happens when it trips. Specify the evidence, who reviews it, and whether the next move is to pause, reduce scope, or return to the decision. Keep the response proportionate to the risk.
Two founders working late at a small table in an empty office
What should you record before work begins?
Write down the choice, its owner, the reason, and the evidence behind it. Add the expected result and what would count as a miss. If the team chooses to ship, record the limits and the conditions that would reopen the decision. If it chooses to refactor, record the acceptance criteria and the point for review.
Keep the record short enough to use when the result arrives. The point is not to defend the original choice. It is to let the team see whether its evidence was sound, whether the work stayed within the boundary, and whether conditions changed. Brainis says predictions carry ranges and a model version, and are preserved unchanged when reality arrives. That leaves the original expectation available for comparison.
Example: A fictional small company chooses to ship a reporting change within a limited scope. Its note names the owner, the test that passed, the functions excluded from the change, and the defect that would trigger a pause. The team also records the expected result and schedules a review after the first user feedback arrives. If that feedback changes the risk, the team can revise the plan without rewriting what it expected beforehand.
Brainis says approved missions include owners, budgets, and acceptance criteria, while the authority contract governs consequential actions. You can review missions and memory to see those product areas. Whether you use software or a shared document, start with the smallest next action that tests the decision. Then set the next check before the team moves on.
Tip: Keep the original expectation alongside the outcome so a later review can distinguish a bad estimate from a changed situation.
Brainis Team
Notes on running a company with Brainis, from the people building it and running on it.