Shotgun Surgery
debt(d7/e7/b7/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated=no and the code_pattern is 'PR touching 10+ files for a single logical change'. While phpstan is listed, it doesn't directly detect scattered responsibilities — this requires a human reviewer noticing the spread of changes across a PR. It's invisible until someone reviews the diff.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix says to consolidate scattered responsibility into one place, but the common_mistakes (DTO, validator, controller, view, test; feature toggles in 20 places; ORM+query builder+raw SQL) all describe changes that are inherently spread across many files and architectural layers. Fixing it means identifying the scattered concern and refactoring all call sites to route through a new centralised abstraction.
Closest to 'strong gravitational pull' (b7). The smell applies_to web, cli, and queue-worker contexts, meaning the scattered responsibility affects all work streams. Every future change to that scattered concern pays the same tax — developers must remember all the places to update, which shapes how every change is made. It doesn't quite reach b9 (no full rewrite needed) but it imposes a strong ongoing burden.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception field explicitly states that developers confuse shotgun surgery with divergent change — treating them as the same smell when they are opposites. This is a well-documented gotcha in refactoring literature that most developers eventually learn, but it's not catastrophic — it's a naming/taxonomy confusion rather than a behaviour-inversion.
Also Known As
TL;DR
Explanation
Shotgun surgery is the opposite of Divergent Change. It occurs when one logical change (e.g. adding a new payment method) forces you to modify many unrelated classes. This indicates that related responsibility is scattered across the codebase rather than centralised. The refactoring is to Move Method and Move Field to bring scattered behaviour together into a cohesive class. High shotgun surgery cost is a strong signal to refactor before adding new features.
Common Misconception
Why It Matters
Common Mistakes
- Adding a new field to a data model and having to update DTO, validator, controller, view, and test separately.
- Not using a single source of truth for configuration that is used in many places.
- Feature toggles checked in 20 different places — centralise in a FeatureFlag service.
- Database column renames that cascade through ORM, query builder, and raw SQL across the codebase.
Code Examples
// Changing VAT rate requires editing 8 different files:
// OrderController.php: \$total * 0.20
// InvoiceService.php: \$price * 0.20
// ReportGenerator.php: \$amount * 0.20
// CartCalculator.php: \$subtotal * 0.20 ...// Single source of truth — one class, one change
class TaxCalculator {
private const RATE = 0.20;
public function apply(float \$amount): float { return \$amount * self::RATE; }
}
// All callers use TaxCalculator::apply() — rate change propagates everywhere