Module Boundaries

Diagnose and fix modules that have grown beyond a single clear purpose, or that have become so entangled with other modules that changes ripple unpredictably. The goal: each module owns one domain of logic, exposes only what callers need, and can be read, tested, and changed without understanding the rest of the system.

When to Apply This Skill

Trigger on any of:

• A single file/module exceeds ~300 lines and handles multiple distinct concerns
• Circular imports between two or more modules
• A module importing from many unrelated parts of the codebase
• Changes to one module routinely break unrelated modules
• "Utils", "helpers", "common", or "shared" modules that have become dumping grounds
• No clear distinction between what a module exposes publicly vs. uses internally
• Multiple modules duplicating the same logic because there's no clear owner