amio/dot-agents/staged-project-maintenance

Staged Project Maintenance

Reduce the cost of maintaining and understanding the project, and improve development efficiency. Remove owned complexity instead of merely rearranging it.

Apply a high-value threshold

Do not optimize for the number of findings or the appearance of cleanliness. Recommend an item only when repository evidence shows that it meaningfully removes concepts, code, state, dependencies, configuration, recurring work, or developer friction, and its expected value outweighs its implementation and regression risk.

A stage may contain a single item; never pad it with marginal work. If a stage has no high-value action, report that plainly and move on. Exclude cosmetic churn, speculative optimization, novelty-driven tool replacement, and abstractions added for hypothetical future needs.

Establish the maintenance scope

Identify the maintenance scope, relevant modules, critical user journeys, and repository constraints. Use the user's stated scope; otherwise audit the project as a whole. Clarify only when ambiguity would materially change the audit.

Record a lightweight baseline of relevant build, typecheck, lint, and test results. Keep pre-existing failures distinct from maintenance regressions.

Work through three stages

Follow these stages in order:

1. Remove dead code and simplify dependencies, configuration, and tooling. Change tooling only when there is evidence of recurring maintenance or development cost.
2. Simplify system design: ownership and module boundaries; state, data flow, persistence, and lifecycle; APIs, abstractions, compatibility paths, and duplicated behavior. Trace symptoms to the highest appropriate owner and fix shared root causes.
3. Consolidate tests and documentation. Remove redundant, low-signal, brittle, or implementation-detail tests while preserving coverage of critical journeys, persistence boundaries, state machines, and complex logic. Remove stale or duplicated documentation and preserve concise knowledge about responsibilities, invariants, and essential workflows.

Complete the following loop separately for each stage.

1. Audit

Inspect the code within the maintenance scope and the governing ownership boundaries and interactions. Audit only the current stage; record cross-stage observations for later without acting on them. Do not modify the repository.

Report only high-value candidates, ranked by expected benefit. For each candidate, provide evidence, root cause, proposed end state, affected modules and approximate code scope, expected maintenance benefit, risk, and validation. Separate verified findings from assumptions.

2. Review gate

Recommend which candidates to execute and wait for explicit user approval. The user may accept any subset, reject all, reorder work, or narrow its scope. Do not modify code before approval.

3. Execute and validate

Implement only the approved items. Preserve unrelated user changes, avoid opportunistic refactors, and remove superseded paths instead of leaving parallel implementations unless compatibility is an agreed requirement.

If implementation reveals scope-expanding work, return it to the review gate instead of silently absorbing it. Run validation proportional to the changed behavior and compare it with the baseline.

Report changes, removals, validation, residual risks, and deviations from the approved plan. Then proceed to the next stage's read-only audit; never execute that stage without its own approval.

Complete the maintenance cycle

After stage three, rerun the relevant baseline checks and inspect the changed areas for leftover duplication or temporary scaffolding. Summarize completed work, deliberately skipped or deferred findings, and remaining risks. Do not claim completion while approved work or introduced regressions remain.