Evidence-Based Refactor Plan

Give One Workflow Permission to Become Durable

A debt board may decide that failed-import recovery needs attention now. That decision gives the work a clock, but not a safe shape. “Refactor reporting” still names only a region of code. It does not say what the founder is protecting or how to know when the work can stop.

A useful plan begins outside the codebase: a workflow has repeated, users rely on it, and its present structure now creates a visible cost or risk.

Use this plan after a debt item has earned attention and before implementation spreads across tickets. It is for structural work on a product path whose value is no longer hypothetical. It is not permission to make the surrounding application elegant.

Start with a short authorization:

REFACTOR AUTHORIZATION

Validated workflow:
Evidence that it has earned durability:
Current failure, delay, risk, or founder burden:
Customer commitment or next product move this work protects:
Why the work has a clock now:

Evidence may be repeated use, payment, retention, support cases, incidents, manual interventions, or a named experiment that the current structure would make unsafe or unreadable. Record actual observations and their limits. If the case reduces to “the code is embarrassing,” return the item to the engineering notebook.

Trace the Product Contract Before Moving Code

Follow one real instance of the workflow from entry to result. At each step, record the input, durable state change, user-visible output, possible failure, and present recovery action. Include the founder’s hidden work. A console command, database correction, or remembered ordering constraint is part of the system even when no user can see it.

Then write the behavior the refactor must preserve. Prefer boundaries users and operators can observe:

CURRENT PRODUCT CONTRACT

Entry condition:
Successful result:
Customer-visible rules that must remain true:
Trust boundaries—access, money, important data, destructive actions:
Known failures and present recovery path:
Behavior that is accidental or still undecided:
Checks that characterize the intended behavior:

Do not silently turn accidental behavior into a permanent contract. If the trace reveals an ambiguous permission rule, duplicate notification, or other customer-visible defect, decide the intended behavior explicitly. That is a product correction traveling with the refactor, not behavior preservation.

Choose the Smallest Structural Commitment

Name what should become easier or safer when the work is done. “Improve the architecture” is not a result. “A failed import can be retried without applying the same data twice, and the founder can diagnose it without querying the database” is.

Draw the boundary in verbs:

• Refactor structure behind a behavior that already deserves protection.
• Delete product surface that no longer deserves representation in the design, after handling any remaining user promise.
• Rewrite only a bounded component whose current representation offers no safe seam; give old and new paths a comparison and migration period.
• Leave alone awkward code attached to an unresolved product question or a variation that has not repeated.

List exclusions with the plan. They should name tempting work, not say “other things.” A refactor of import recovery might exclude new connectors, a general job framework, enterprise roles, unrelated template duplication, and scale beyond the next evidenced range. Exclusions keep the product’s open questions cheap to answer.

Plan Checkpoints That Can Survive Interruption

A solo founder rarely receives a quiet refactor season. Break the work into checkpoints that preserve a usable product and can stop independently.

1. Pin down the earned behavior with boundary or characterization checks.
2. Make the current failure legible before changing its internal path.
3. Introduce one seam around the validated workflow.
4. Move one behavior or state transition behind that seam and observe it.
5. Migrate data or traffic in a bounded slice when the design requires it.
6. Remove the old path only after the replacement has proved recoverable.
7. Delete obsolete code, flags, data, checks, and operating instructions.

For each checkpoint, specify what can be observed and how to recover. “Revert the deployment” is incomplete when new records or irreversible side effects may already exist. Name compatible code versions, schema consequences, data reconciliation, delivery duplication risk, and the last point at which the old path remains trustworthy.

When customer data changes, prefer an expand-and-contract sequence when it is safer: add the new representation, migrate or compare a small slice, move reads, stop old writes, and remove the old form later. Dual writing can itself diverge, so state whether a transaction, reconciliation record, maintenance window, or another control makes the transition honest. Confirm that a backup can be restored before relying on it.

The Working Plan

Keep the plan in one living record. Link evidence and technical details rather than burying the decision in a wall of prose.

EVIDENCE-BASED REFACTOR PLAN

Authorization
  Validated workflow:
  Evidence and observation window:
  Current consequence:
  Commitment or next move protected:

Product contract
  Entry and successful result:
  Behavior to preserve:
  Trust boundaries:
  Known failure and recovery:
  Deliberate behavior correction, if any:

Structural decision
  Smallest useful outcome:
  Refactor:
  Delete:
  Rewrite:
  Leave alone:
  Explicit exclusions:

Safe sequence
  Checkpoint 1 — change, observation, recovery:
  Checkpoint 2 — change, observation, recovery:
  Checkpoint 3 — change, observation, recovery:
  Data or traffic migration:
  Old-path removal condition:

Finish
  User or operator outcome:
  Founder-leverage measure and baseline:
  Product-change lead-time measure and baseline:
  Safety evidence:
  Stop condition:
  Review trigger for the remaining debt:

The four structural lines need not all contain work. Their purpose is to force different decisions. An awkward source adapter may remain; a report-run state model may be refactored; an unused freelancer branch may be deleted; one ambiguous permission check may need bounded replacement.

A Worked Plan for Weekly Agency Reports

Suppose small agencies repeatedly import source data and deliver a weekly report. Import failures have required founder console work, and late reports have generated support calls. The plan could make these commitments:

Validated workflow:
  Import source data, review one report, and deliver it each week.

Smallest useful outcome:
  A failed import has an inspectable state and a safe retry; the same input
  cannot create a second report or delivery.

Refactor:
  Put import and delivery transitions behind one report-run boundary.
  Attach diagnostics and access checks to the same stable run identity.

Delete:
  Retired import flags and the console-only recovery instructions once no
  supported account depends on them.

Rewrite:
  None; the live path has seams that permit incremental replacement.

Leave alone:
  The single-source adapter and duplicated report-section rendering.

Explicit exclusions:
  New connectors, a plug-in system, generalized job orchestration, new roles.

Safe sequence:
  Characterize current report output and access rules.
  Record explicit run states while the old worker still executes the job.
  Enable safe retry for internal accounts, then a small customer slice.
  Compare deliveries and retain old-path recovery until every observed
  mismatch is explained and the agreed observation window closes.

Stop condition:
  The founder can diagnose and retry a failed run without database editing;
  forced retry cannot duplicate data or delivery; the next validated report
  change does not require changing recovery code.

The plan does not promise a clean reporting platform. It protects one paid result and removes one private operating ritual. That is enough authority for the work and enough constraint to finish it.

Manage the Plan While the Code Is Open

Update the record when evidence changes, not whenever implementation produces a new idea. If a checkpoint uncovers broader coupling, first ask whether the validated workflow requires that coupling to be removed. Add scope only when the customer promise, safety boundary, or named next move cannot be protected without it.

Pause when the refactor changes product behavior without a decision, when a migration cannot be recovered, or when the original evidence has weakened. Stop when the observable finish conditions are true. Remaining ugliness should receive a trigger, not automatic admission to the project.

The finished plan should let a skeptical reader answer five questions: why this workflow earned durability, what behavior is protected, which structural commitment is being made, how each risky step can recover, and what evidence will close the work. If it cannot do that, implementation is still being asked to discover the decision.