Horizontal bloat - Too many files/classes for simple features
Vertical depth - Too many jumps to find core logic

DETECTION CHECKS (Run in Parallel)

Horizontal Bloat (Over-abstraction)

ID	Grep Pattern	Smell	Fix
single-impl	`interface I[A-Z]` + count `implements` = 1	Interface with 1 impl	Delete interface
future-proof	`Factory\|Strategy\|Provider\|Builder`	Pattern with 1 product	Use class directly
generic-repo	`extends Base\|extends Abstract\|<T>`	Base class with overrides	Inline to each class
enterprise-larp	Glob `*/Theme*` > 5 files	11 files for dark mode	1 useState

Vertical Depth (Hide-and-seek Code)

ID	Grep Pattern	Smell	Fix
deep-call	Private methods > 3 levels deep	`this._a()` → `_b()` → `_c()` → `_d()`	Inline or flatten
scattered-flow	Steps A,B,C in separate functions	`stepA(); stepB(); stepC();`	Keep linear in one fn
hidden-state	Heavy use of `this.` in methods	State buried in class members	Pass as explicit params
vague-name	`processData\|handleStuff\|doWork`	Generic function names	`calculateMonthlyTotal`

Traceability Issues

ID	Grep Pattern	Smell	Fix
unsearchable-error	Duplicate error strings	Same "Failed" in 5 places	Unique error codes
missing-context	`throw new Error("failed")`	No diagnostic context	Include why + inputs
what-not-why	`// increment i` style comments	Explains what, not why	Document business reason

QUICK CHECKS

# Horizontal: abstraction patterns
Grep("Factory|Strategy|Provider|Builder|Orchestrator", path="<dir>", output_mode="content", -n=true, head_limit=20)
Grep("interface I[A-Z]|abstract class|extends Base", path="<dir>", output_mode="content", -n=true, head_limit=20)

# Vertical: call depth indicators
Grep("private.*\(|this\._[a-z]", path="<dir>", output_mode="content", -n=true, head_limit=20)
Grep("processData|handleEvent|doWork|execute\(\)", path="<dir>", output_mode="content", -n=true, head_limit=20)

# Traceability: error/log patterns
Grep("throw new Error|console\.(error|log)", path="<dir>", output_mode="content", -n=true, head_limit=20)

REVIEW CHECKLIST

When reviewing, check:

Jump test: Need > 3 jumps to find core logic? → Inline
Search test: Can grep error message → exact line? → Make unique
Context test: Error includes why + inputs? → Add context
File ratio: > 5 files for simple feature? → Consolidate

DECISION RULES

Split function ONLY when:

Logic reused 3+ times (Rule of Three)
Split significantly reduces cognitive load
NOT just because "it's too long"

Keep linear flow:

// BAD: scattered
stepA(); stepB(); stepC();

// GOOD: visible
// Step A: validate input
if (!valid) return err;
// Step B: transform
const result = transform(data);
// Step C: persist
await save(result);

Naming for grep:

// BAD: generic
catch(e) { throw new Error("Operation failed") }

// GOOD: searchable
catch(e) { throw new Error("PAYMENT_CALC_001: Monthly total failed", { customerId, month }) }

RED FLAGS

Stop if you hear:

"We might need this someday"
"This is more professional"
"I learned this pattern"
"This won't scale" (no evidence)
"Let's make it configurable"

pragmatic-architecture

OUTPUT FORMAT

CORE PRINCIPLES