REPAIR VS REBUILD
Repair, refactor, rebuild, or restart?
The right answer depends on more than the visible bug. A useful decision must consider product value, project evidence, architecture clarity, test safety, operational state, risk, time, cost, and the quality of the current handoff.
PRACTICAL FRAMEWORK
Eight dimensions for a provisional decision
Review business and technical constraints together. No single visible failure determines the right path.
Product fit — Does the existing product still solve the right problem?
Repository understanding — Can the active code, dependencies, configuration, and deployment path be identified?
Architecture clarity — Are the major boundaries understandable and maintainable?
Test safety — Can important behaviour be reproduced and protected?
Operational risk — Are migrations, credentials, hosting, integrations, and data handling understood?
Documentation quality — Do current records match the implementation?
Repair scope — Can the problem be isolated without expanding into an uncontrolled rewrite?
Business constraints — What time, budget, continuity, and delivery pressures shape the decision?
CURRENT FRAMEWORK
Four possible outcomes
- Repair
Fix a bounded issue without changing the core structure.
- Refactor
Improve internal structure while preserving product behaviour.
- Rebuild
Replace major technical foundations while preserving product direction.
- Restart
Return to product definition because the project no longer supports the intended outcome.
Read visual as text
Repair fixes a bounded issue without changing the core structure. Refactor improves internal structure while preserving behaviour. Rebuild replaces major technical foundations while preserving product direction. Restart returns to product definition when the project no longer supports the intended outcome.
DECISION CHECKLIST
Evidence required before the decision hardens
The quality of the conclusion cannot exceed the quality of the repository, test, deployment, operational, and product evidence supporting it.
Confirm that the current product direction still serves the intended user.
Identify the active repository, branch, configuration, and deployment path.
Review the architecture boundaries and known coupling.
Reproduce important behaviour and establish test safety where possible.
Understand data, migration, credential, hosting, and integration risk.
Compare documentation with the implementation.
Bound the repair scope and expose expansion risk.
Record time, budget, continuity, and delivery constraints.
| Dimension | Decision question | Evidence to review |
|---|---|---|
| Product fit | Does this still solve the right problem? | User outcome, current use, product direction |
| Repository understanding | Can the active implementation be identified? | Repository, branch, dependencies, configuration |
| Architecture clarity | Can change remain bounded? | Major boundaries, coupling, data flow |
| Test safety | Can important behaviour be protected? | Reproduction steps, tests, acceptance criteria |
| Operational risk | Can change avoid uncontrolled impact? | Deployment, data, migrations, integrations |
| Business constraints | Which path is viable now? | Time, budget, continuity, delivery pressure |
CURRENT FRAMEWORK
Evidence-threshold flow
- Supplied context
- Repository review
- Test evidence
- Operational review
- Provisional direction
- Authorised work
Read visual as text
The evidence flow is supplied context, repository and test review, deployment and data verification, provisional direction, decision review, and bounded implementation authority.
COMMON MISTAKES & RISKS
Common decision risks
A fast answer can be more expensive than a provisional answer that makes its evidence threshold explicit.
Deciding from the visible bug alone.
Letting sunk cost determine the next technical path.
Assuming documentation describes the active implementation.
Estimating repair without test or deployment evidence.
Rebuilding before confirming the product direction.
Treating a broad refactor as a bounded repair.
Presenting a supplied-context conclusion as final or certified.
CURRENT PRODUCT MAPPING
How this framework maps to Airchor today
Work on Existing Project can organise the reported project state, source of truth, manual findings, risks, recovery roadmap, and developer handoff around this decision.
CURRENT LIMITATION
The conclusion remains provisional
A repair-versus-rebuild conclusion based only on supplied context is provisional. The actual repository, tests, deployment, and technical evidence must be reviewed before implementation is authorised.
- Not an automated audit or formal due diligence
- Not a technical guarantee or certified recommendation
- Not a repair quote
NEXT ACTION