Turning code review findings into a tested upgrade plan

The three prototypes already contained months of useful domain work. My task was to make that work maintainable without changing what it did.

On the same day I used my code review runbook to review a client's product, I applied it to three internal prototype repositories. The client review produced findings and recommendations. For the prototypes, I owned the fixes. The framework helped me organize an upgrade and decide what evidence each change needed.

I hadn't planned that use. It became the framework's most powerful property for me: the work of understanding the code could carry directly into improving it.

September 2026 update: The runbook is now the synthesis-codebase-review Agent Skill.

Respect the work already in the prototypes

A VP of Marketing, not an engineer, had built the three agent prototypes with AI coding tools. The applications contained sophisticated domain logic, but their engineering fundamentals needed attention: TypeScript that wouldn't compile, a 3,610-line React component, hardcoded paths to a developer's desktop and no tests. The goal was to bring the repositories to a standard where professional software engineers could take over development.

I nearly fell into a familiar trap: seeing inconsistent formatting, mixed patterns and missing tests, then treating the whole thing as code to replace.

One prototype contained a multi-factor scoring model with weighted criteria and bias detection. Another implemented a human-in-the-loop decision workflow with status transitions and approval chains. The third had a predictive analytics framework with population-level modeling.

The business logic was sophisticated and correct. A domain expert had spent months refining those algorithms. Reconstructing that knowledge from scratch would have taken weeks of requirements gathering. The roughness around it was an engineering problem I could address without discarding the asset.

I made the preservation constraint explicit: no functionality changes, no feature additions, no scoring algorithm changes. Before restructuring anything, I wrote tests for pure functions with deterministic behavior: similarity calculations, input validation rules and state transitions. Those characterization tests recorded what the functions did before the upgrade, so an accidental change would have something concrete to disagree with.

The tests also became executable documentation. An engineer picking up a scoring function could read its cases and expected results instead of reconstructing the rule from the implementation alone.

Six kinds of work, with real dependencies

The review organized the upgrade into build fixes, documentation, linting and formatting, structure, testing, and security. The sequence follows the dependencies of the particular change and the consequences of waiting.

Build problems were concrete. One repository had missing types, function signatures that didn't match callers and local definitions conflicting with framework globals. Another depended on paths such as /Users/dev/Desktop/.... A third had dependency conflicts that prevented npm run build from completing. Fixing these made the applications reproducible on a working engineer's machine.

I would start an upgrade plan by identifying urgent exposures and recording a baseline: the source commit, available build commands, observed failures and behavior to preserve. A potentially exposed credential needs its owner's revocation or rotation response promptly. Moving its value into an environment variable doesn't retire the old credential, and formatting isn't a prerequisite for acting on it.

Other work can proceed alongside build repair. Type checking and linting are different analyses. A type error doesn't by itself make ESLint unusable. A missing parser, invalid configuration or a rule dependent on unavailable build output can block a particular lint run. Record that actual dependency. Run the checks whose inputs are available.

WorkWhat it contributesWhat determines its order
BuildReproducible commands; repaired types, signatures, paths and dependency conflictsNeeded before checks that execute or depend on that build
DocumentationARCHITECTURE.md, README.md and .env.example explain the application and its setupRecord understanding during investigation, before restructuring erases useful context
Linting and formattingESLint, Prettier and consistent conventionsThe parser, configuration and particular rules must be usable
TestingCharacterization, requirement checks and regression evidenceCapture behavior before changing the code that implements it
StructureFocused modules, separated responsibilities and testable boundariesUnderstand the responsibilities and protect the behavior being moved
SecurityEnvironment variables, .env.example, ignore rules, access checks and credential handlingUrgent exposure takes priority; continue checking consequences throughout the work

For a component split, the dependency chain is straightforward:

record baseline → characterize behavior → split responsibilities → check integration

credential response: act promptly through the owner
independent formatting: can proceed when its own tooling is usable

A large file doesn't prevent meaningful tests. In this upgrade, testing the pure domain functions before restructuring was precisely how I protected the useful work inside it.

Use tiers to control scope

These were internal prototypes used by a small team. They weren’t customer-facing, didn’t handle PII and weren’t subject to compliance requirements. We selected Tier 2, Standard, which the runbook then described as roughly 150 checks. That scope helped me resist building a larger platform around applications whose immediate need was an engineer handoff.

Without that discipline, I know what would have happened. I would have added authentication, database migration frameworks, CI/CD pipelines, Docker containerization and multiple deployment environments by habit. Instead, I concentrated on usable builds, ESLint, Prettier, tests, documentation and clean architecture.

Each infrastructure choice still deserves its own reason. An internal service used by three people to approve valuable records needs a defined access boundary. The important questions are who may act, on which resources, and with what consequences; authorization guidance starts from those relationships. A local, disposable example with synthetic data, no network access, no shared access and no persistent state may need no new login service. A stateless prototype may need no database migration framework. Containers and multiple environments should earn their place through actual delivery and recovery needs.

Tiering’s biggest benefit in this work was helping me stop adding things by habit. I wanted the infrastructure the handoff actually needed, with a reason for each choice.

The single highest-impact change

Decomposing the monolith created more engineering value in this upgrade than all the other changes combined.

The main component was 3,610 lines: the entire UI, 24 useState hooks, inline mock data, deeply nested conditional rendering and alert() calls for feedback. Work on separate features kept converging on the same file. That made collaboration and review harder than they needed to be.

I split it into 17 focused modules: a mock data layer, custom hooks, shared components, view-specific components, modals and a notification system replacing alert(). The main file fell to 212 lines. Replacing alert() changed the feedback interaction. The domain algorithms remained the behavior we were protecting.

An engineer could then work on the scoring workflow while another changed the audience brief modal in its own module. Shared interfaces could still require coordination, but the two tasks no longer had to start in the same giant component. Linting and documentation helped the current developers. The decomposition changed how future work could be divided.

When evaluating an upgrade, I start by inspecting the largest file. I'd flag handwritten application files over 500 lines as decomposition candidates and require a decomposition plan for those over 1,000. I want a specific reason to keep a file that large. Length directs my attention; responsibilities and likely changes determine the split. A generated 1,200-line lookup table may be one cohesive artifact. A 350-line file mixing pricing, authorization and email delivery can deserve attention sooner.

Check preservation and the intended result

Characterization protects behavior during a refactor. A requirement check supplies an expected answer independently of the old implementation. Both are useful, and they can disagree without giving the refactor permission to change the business rule silently.

Consider a fictional scoring example, unrelated to the three prototypes' algorithms. Inputs quality and reach are integers from 0 through 100, with booleans, fractions and out-of-range values rejected. The old function calculates:

score = (3 * quality + reach) // 4
result = {"score": score, "eligible": score > 60}

The refactored function preserves that calculation. A separately written fictional requirement says that eligibility includes 60.

InputOld functionRefactored functionIndependent requirement
Quality 100, reach 0Score 75, eligibleScore 75, eligibleScore 75, eligible
Quality 0, reach 100Score 25, ineligibleScore 25, ineligibleScore 25, ineligible
Quality 60, reach 60Score 60, ineligibleScore 60, ineligibleScore 60, eligible

The refactor preserves all three results. The boundary case still fails the independent requirement. That discrepancy belongs in a separate work item and a decision about the intended rule. Quietly changing > to >= while claiming a structure-only refactor would hide a behavior change.

Integration needs its own check too. With quality 80 and reach 0, the function should return 60. An adapter that swaps the fields calls it with quality 0 and reach 80, producing 20. The function's isolated tests can all pass while the request path is wrong.

The upgrade workbook provides both implementations, the correct and broken adapters, and twelve scenarios for work ordering, evidence, access decisions and design boundaries. The twelve scenarios have fixed expectations written before the implementation. The exercise runs locally with Python's standard library; it neither upgrades a real repository nor grants domain approval.

Turn a finding into work someone can finish

“Testing” identifies a review category. A finding such as swapped adapter fields identifies a repair. For the fictional example above, a usable work item looks like this:

FieldWork item
Finding IDF-score-adapter
Observed problemThe adapter reverses quality and reach; input 80/0 returns 20
Desired behaviorThe request reaches the scorer with its fields intact and returns 60
Protected behaviorKeep the scoring weights, integer arithmetic and existing eligibility rule
UrgencyResolve before handing this request path over as checked
PrerequisitesBaseline plus characterization of the scorer
Proposed changeCorrect the adapter's argument mapping
Acceptance criterionSend quality 80/reach 0 through the adapter and require score 60, ineligible
EvidenceThe workbook's request-path check distinguishes correct output 60 from broken output 20
Acceptance ownerEngineer for the mapping repair; domain owner for the eligibility rule
Remaining decisionResolve the separately identified eligibility boundary at 60

A checked box without the evidence doesn't complete that row. The workbook treats a plan with an empty evidence list as unsupported. It also checks dependency graphs: a missing prerequisite or a cycle is visible. Ready urgent work goes first; if it is blocked, its prerequisites go ahead of unrelated routine tasks. Independent tasks at the same priority may start in either order. That makes the plan useful for dividing work without hiding the things one task needs from another.

Repeat the setup; understand each domain

Across the three repositories, build fixes, documentation, tooling and security cleanup followed repeatable patterns. We reused ESLint configuration patterns, the structure of ARCHITECTURE.md and the .env.example convention. Independent setup work could proceed in parallel, with each repository's commands and configuration checked afterward.

Only one repository needed the 3,610-line component decomposition. Testing required understanding each application's scoring algorithms, data structures and edge cases. A template could organize that investigation; it couldn't supply the domain answers.

The upgrade produced 286 tests, documentation and substantial structural changes across the three repositories. The right framing for the stakeholder was: “This is an overhaul, close to a complete rewrite. We preserved all business logic, but integrations may be broken. The next step is testing with the domain expert.”

Calling it “some cleanup” would understate the work and the testing still needed. The engineer understands the implementation; the domain expert understands the intended result. Bring that expertise into defining independent expectations and reviewing the handoff. Passing engineering tests doesn't substitute for that acceptance.

I built the codebase review framework to find problems. When I owned the changes, its findings became the starting point for a much more useful deliverable: a plan naming what to preserve, what to change and how to tell whether the change worked. On a codebase you own, carry those findings into the upgrade. Keep the valuable domain work visible while you make it easier for the next engineer to develop.


This article is part of the code review series. See also: Code review that scales (choosing review depth) and What reviewing real codebases taught me about code review (conducting and interpreting a review).