Refactor Architecture
Improve the structure of code that already exists. The goal is deep
modules, a lot of behaviour behind a small interface, and locality, so
a change lives in one place. Read references/vocabulary.md when a term
below reads unfamiliar; it defines the words these steps lean on: module,
interface, depth, seam, adapter, leverage, and the deletion test.
When to use
- An existing codebase has friction: a change bounces you across many files, modules are thin wrappers, tests couple to internals, seams leak.
- Skip for greenfield design (
system-architecture), a one-off local fix, or a read-only audit:complexity-auditowns that and hands an accepted structural finding here.
Step 1: Classify and measure
- Open
assets/structural-proposal.mdbefore classifying, and fill its High-risk classification section. If all four answers are on the ordinary route, stay here. If any answer is not, invokemigration-strategyandverification-strategy, then wait for their approved, current contracts and for the entry gates to pass. Work authorized as a prerequisite takes in only its exact proposed contract; it cannot edit the target, approve the contract, or satisfy entry. - Pin down the exact source revision, the contracts it must honour, and the external inputs it consumes.
- Inventory the surface and the friction, giving each item a stable ID. Trace callers, behavior, the performance and resource profile, and the compatibility surface. Friction that has not been measured is a preference.
- REQUIRED SUB-SKILLS: invoke
using-git-worktrees, thentest-driven-developmentfor the preservation cycle in that workspace: the baseline green, a deliberate divergence red, the exact restoration green. An oracle that is compile-only or derived from the target is not enough.
Step 2: Decide the structure
Run the deletion test on each suspect module. If removing it would spread complexity to its callers, keep it. If the complexity would merely relocate, collapse it.
Add a seam only for repeated behavior with a stable owner and measured change friction, or for one real volatile or external boundary with measured impedance, failure policy, or test isolation. Never add one for implementation count or for hypothetical variation.
Fill the rest of the proposal before presenting it. The decision outcome and the slice progress go in the ledger beside it, never in it.
If a choice is hard to reverse, invoke
architecture-decisions.Present the proposal. Never pick the structure yourself:
Structural proposal {{identity (per template)}} Friction: {{measured, one line}} Target: {{one line}} Alternatives: {{list}} Slices: {{n}} Rollback: {{one line}} 1. Approve under the preservation gate 2. Request changes 3. Reject and retain the current structure 4. Cancel Recommendation: {{option the friction and recovery evidence support}} — {{one sentence}}.Ask this and end the turn;
clarifying-intentowns what closes it. Option 2 issues a successor proposal and asks again; 3 and 4 end here, recorded in the ledger, and the Step 1.4 worktree and tests stay until the user settles them throughfinishing-a-branch.If the inputs drift, or what was approved changes, that needs an approved successor, and the slices it affects are invalid.
Step 3: Transform under preservation
- Only after the exact scope and the decision authority are in place,
REQUIRED SUB-SKILLS: invoke
test-driven-developmentandyagni. If the slices take more than one step, invokewriting-plans; its mode answer names the executor. A slice that is one mechanical change across many files goes tolarge-scale-changes. - For each slice: migrate its callers, run the checks its row of the slice
table names (Step 1.4's preservation tests and the project's own),
compare against the measurements in the proposal's Now section, and
retain the known-green state. Checkpoint under
using-git-worktrees. Rewrite a test that reaches into internals against the interface in an earlier slice of its own, never in the slice that moves its target. - If a behavior delta appears, stop. Return to its requirement or to a new-behavior cycle.
- Before removing, moving, or renaming a surface, inventory every path
that could still reach it: static calls, dynamic registration,
reflection, configuration, generated inputs, tests, and external
consumers, plus its name as a string (dynamic imports, entry-point
declarations, CI path filters, ownership globs, patch targets in tests).
If unsure, it stays, or waits for
deprecating-an-api's removal approved and the migration. - Map every invariant the surface carried to the coverage that survives. Falsify that surviving gate. Keep the rollback recoverable until integration.
Gotchas
- The deletion test's "removal spreads complexity to callers" branch is only as good as the caller trace behind it: run it against a guessed caller set and a genuinely load-bearing module reads as a thin wrapper worth collapsing.
Common mistakes
- Refactoring for tidiness, not leverage: change structure only where it cuts real friction.
- Combining so many structural moves that behavior, performance, compatibility, or rollback can no longer be attributed to one slice.