Loop 069
The architecture-preserving code refactor loop
An AI coding-agent workflow for improving a targeted code area through dependency mapping, atomic refactors, baseline tests, and downstream regression checks without changing architecture or public contracts.
Ready-to-use prompt
Copy the loop
Refactor [target] toward [measurable goal] in [repository]. If the target or goal is missing, ask and stop. Record current behavior and affected dependencies; select representative tests for boundaries and failure modes, then make one atomic change without altering public contracts unless authorized. Run the same tests, type and lint checks, and affected-consumer checks, keeping only regression-free improvements. Repeat for at most five rounds. Stop on success, blocked architecture, approval required, exhaustion, or no progress. Preserve unrelated work and finish with the diff, impact map, evidence, rejected attempts, and remaining debt.
Verify / stop
The target improves without changing contracts or downstream behavior.
The stated measurable goal is met, baseline behavior and public interfaces remain intact, and the relevant tests, type checks, lint checks, and affected-consumer checks pass under recorded conditions.
Context and guidanceWhen to use it, steps, safety notes, and related loops
Use this when
Use this for a focused readability, typing, maintainability, or performance refactor whose intended behavior and public contracts should remain unchanged.
How to run it
- Define the target, measurable goal, current behavior, public contracts, and applicable baseline checks.
- Map internal call sites, upstream dependencies, and downstream consumers using the repository evidence available.
- Select or add representative tests for boundaries, type constraints, and failure modes without forcing arbitrary coverage work.
- Apply one atomic refactor and rerun the baseline, static checks, and affected-consumer checks.
- Keep only verified improvements and repeat for no more than five rounds before entering a terminal state.
Why it works
A blast-radius map prevents a locally attractive change from breaking consumers elsewhere. Atomic iterations and fixed checks make it possible to reject a failed attempt without compounding uncertainty across later changes.
Implementation note
Do not discard unrelated work, modify public signatures or contracts without authorization, or manufacture a clean result by weakening tests or checks. An AST or generated dependency graph is optional when direct repository evidence provides a clearer impact map.
Contributor playbookBoundaries, required outputs, implementation guidance, and reviewer handoff
Do not use this when
- Do not use this loop when the goal intentionally changes public contracts or system architecture unless that broader scope is explicitly authorized.
- Do not start when neither a reproducible baseline nor a credible behavior check is available.
Required outputs
- A successful refactor diff, impact map, validation evidence, rejected attempts, and a concise note about remaining technical debt.
- A blocked or exhausted report when five rounds cannot reach the stated goal safely.
Match the method to the artifact
- Prefer direct call-site and dependency evidence; generate an AST or dependency graph only when it materially improves the impact analysis.
- Test representative boundaries, type constraints, and failure modes rather than inventing a fixed test count or coverage claim.
- Reject only the current failed attempt while preserving unrelated user work and earlier verified improvements.
Reviewer handoff
- Confirm that the public interface and affected consumers retain their expected behavior.
- Treat unavailable baselines, structurally broken dependencies, and exhausted rounds as explicit non-success outcomes.