Reduce change fan-out
Reduce fan-out by finding the responsibilities and contracts that make ordinary changes travel too far, then redesigning for locality of change instead of only tidier structure.
- Situation
- Small changes spread across too many files, modules, or teams.
- Goal
- Make common changes smaller, safer, and more local by reducing hidden coupling and misplaced logic.
- Do not use when
- the work is genuinely cross-cutting by business nature and not repetitive enough to redesign around
- Primary owner
- tech lead
- Roles involved
tech leadarchitectmaintainers of affected areasdelivery lead if fan-out is hurting roadmap flow
Context
The situation
Deciding whether to reach for this playbook: when it fits, and when it doesn't.
Use when
Conditions where this playbook is the right tool.
- Routine changes require edits across many services, layers, or repos
- Feature work triggers coordination that feels disproportionate
- Bug fixes often require multi-team validation
- The team says simple changes are never simple anymore
Stakes
Why this matters
What this playbook protects against, and why skipping or half-running it tends to be expensive.
Wide change surfaces slow delivery and make systems fragile. If ordinary changes require many synchronized edits, the architecture is externalizing complexity onto humans.
Quality bar
What good looks like
The observable qualities of a team or system that is actually doing this well. Not just going through the motions.
Signs of the playbook done well
- Common changes touch fewer units
- Logic lives closer to its owning boundary
- Contracts carry more meaning so fewer downstream compensations are needed
- Coordination effort drops for everyday work
- Teams know why a change is local or why it is not
Preparation
Before you start
What you need available and true before running the procedure. Skipping this is the most common reason playbooks fail.
Inputs
Material you'll want to gather first.
- Recent changes with high fan-out
- Dependency graph
- Service or module ownership map
- Test and release coupling patterns
- Contract and schema relationships
Prerequisites
Conditions that should be true for this to work.
- You can identify recent high-fan-out changes
- The team is willing to challenge current boundary and layering assumptions
- There is enough observability into code and coordination patterns
Procedure
The procedure
Each step carries its purpose (why it exists), its actions (what you do), and its outputs (what you produce). Read the purpose. It's what keeps the step from degenerating into checklist theatre.
Find real fan-out cases
Anchor the work in actual change pain, not abstract taste.
Actions
- Collect examples of routine changes that spread too far
- Classify the spread by layer, service, repo, or team boundary
- Identify whether the fan-out is structural or incidental
Outputs
- Fan-out case set
Trace why the change had to spread
Locate the coupling mechanism behind the visible edits.
Actions
- Identify shared schemas, duplicated rules, boundary leaks, and synchronized release needs
- Ask which change was primary and which edits were compensating edits
- Find where source of truth is ambiguous
Outputs
- Coupling cause map
Choose the locality lever
Reduce fan-out through the right intervention, not generic cleanup.
Actions
- Decide whether to move logic, tighten contracts, consolidate ownership, or reshape the boundary
- Prefer the smallest change that improves locality for repeated work
- Avoid broad redesign when one clearer contract would solve most of the spread
Outputs
- Locality intervention plan
Improve one repeated path first
Prove locality gains on a real pattern.
Actions
- Pick one high-frequency fan-out path
- Apply the chosen structural fix
- Measure whether the next similar change stays smaller
Outputs
- Pilot locality fix
Bake locality into design review
Stop new fan-out from reappearing invisibly.
Actions
- Add change-locality questions to design and review rituals
- Flag new work that expands ordinary change surfaces
- Teach the team to notice compensating edits early
Outputs
- Change locality review guide
Judgment
Judgment calls and pitfalls
The places where execution actually diverges: decisions that need thought, questions worth asking, and mistakes that recur regardless of good intent.
Decision points
Moments where judgment and trade-offs matter more than procedure.
- Is the fan-out caused by ownership, contracts, or misplaced logic?
- Should we move behavior or improve the interface around it?
- Is one source of truth missing?
- What locality improvement is worth the cost right now?
Questions worth asking
Prompts to use on yourself, the team, or an AI assistant while running the procedure.
- Which ordinary change patterns travel too far?
- What part of the fan-out is real, and what part is compensation for weak boundaries?
- What is the smallest structural move that would make the next similar change more local?
Common mistakes
Patterns that surface across teams running this playbook.
- Treating every wide change as inevitable complexity
- Optimizing file structure while leaving source-of-truth problems intact
- Splitting code further when the problem is actually fragmented ownership
- Changing too much at once before proving locality gain
Warning signs you are doing it wrong
Signals that the playbook is being executed but not landing.
- Common changes still require the same multi-area edits after the intervention
- The team cannot explain which edit is now authoritative
- Locality is discussed in theory but not measured on repeated work
- The fix creates more abstractions than reduced fan-out
Outcomes
Outcomes and signals
What should exist after the playbook runs, how you'll know it worked, and what to watch for over time.
Artifacts to produce
Durable outputs the playbook should leave behind.
- Fan-out case set
- Coupling cause map
- Locality intervention plan
- Change locality review guide
Success signals
Observable changes that mean the playbook landed.
- Repeated changes become smaller and more local
- Coordination effort declines for common work
- Source-of-truth questions get easier to answer
- The team starts identifying fan-out risks earlier in design
Follow-up actions
Moves that keep the playbook's effects compounding after it finishes.
- Apply the same analysis to the next repeated fan-out pattern
- Refresh ownership and contract docs after locality improvements
- Teach reviewers to call out compensating changes explicitly
Metrics or signals to watch
Longer-horizon indicators that the underlying problem is receding.
- Average number of repos or services touched per routine change
- Multi-team review count per common feature
- Time lost to synchronized edits
- Number of duplicated rule edits per release
AI impact
AI effects on this playbook
How AI-assisted and AI-driven workflows help execution, and the ways they can make it worse.
AI can help with
Where AI tooling genuinely reduces the cost of running this playbook well.
- Finding common multi-file or multi-repo change patterns
- Summarizing repeated compensating edits from commit history
- Highlighting duplicated business logic and schema dependencies
AI can make worse by
Distortions AI introduces that make the underlying problem harder to see.
- Making cross-cutting edits cheaper without reducing the structural cause
- Spreading identical mistakes faster across many layers
- Encouraging broad automated edits that hide poor locality
Relationships
Connected playbooks
Failure modes this playbook tends to address, decisions behind the situation, red flags that motivate running it, and neighboring playbooks.