refactor-squatters
Detect squatters: modules and packages that occupy namespace positionsthey do not semantically own. Identifies utility dumps, stuttery siblings,axis violations, layer bleeding, and semantic diffusion — common structuralsmells introduced by agentic programming.
When & Why to Use This Skill
The Refactor-Squatters skill is a specialized diagnostic tool designed to maintain software architecture integrity by identifying 'squatters'—modules and packages that occupy incorrect namespace positions. It targets common structural smells often introduced during rapid development or agentic programming, such as utility dumps, layer bleeding, and semantic diffusion, ensuring the codebase remains navigable and semantically aligned with the domain model.
Use Cases
- Auditing AI-generated codebases to identify and fix structural shortcuts where 'making it work' was prioritized over proper domain modeling.
- Refactoring bloated 'common', 'utils', or 'helpers' packages by identifying the true semantic home for misplaced functions and modules.
- Detecting 'stuttery siblings' where module naming compensates for poor directory structure (e.g., fixing 'user_service.py' sitting redundantly next to a 'user/' package).
- Enforcing architectural boundaries by identifying 'layer bleeding' where modules cross defined system tiers in a way that violates design invariants.
- Improving codebase discoverability for both human developers and AI agents by ensuring the filesystem accurately reflects the conceptual domain.
| name | refactor-squatters |
|---|---|
| license | MIT |
| description | | |
| Detect squatters | modules and packages that occupy namespace positions |
| author | Jordan Godau |
Instructions
Read all references in references/ before using this skill.
What is a Squatter?
A squatter is a module or package that occupies a namespace position it does not semantically own.
In real estate, squatters occupy property without legal claim. In codebases, squatters occupy import paths without conceptual legitimacy. They exist because:
- Agentic programming prioritizes "make it work" over "make it belong"
- Domain modeling was deferred — the code landed somewhere expedient
- Compensatory naming masked the misplacement (e.g.,
las_fields.pyinstead oflas/fields.py)
Squatters degrade navigability. A developer (or agent) cannot guess where code lives because the filesystem lies about ownership.
Central Invariant
Every module should be importable from a path that a domain expert would guess correctly.
If a module name compensates for weak structure, or sits beside a package it should be inside, the filesystem is lying about the domain model.
Signals
- Reviewing package structure after significant growth
- Noticing
common/,utils/, orhelpers/packages - Seeing modules with underscore prefixes matching sibling package names (e.g.,
las_fields.pybesidelas/) - Finding single-function modules that only wrap a foreign dependency
- Observing imports that cross architectural layers upward
References
Directory: references/
01_GOAL.md— What this skill accomplishes02_DEFINITIONS.md— Vocabulary for squatters and namespace violations03_INVARIANTS.md— Rules that determine violations04_HEURISTICS.md— Detection patterns and signals05_PROCEDURE.md— Step-by-step audit process06_REMEDIATION.md— Refactoring directions (hypotheses, not mandates)07_OUTPUT.md— Report format and severity classification
Scripts
Directory: scripts/
detect.sh: Scan for structural smells (macOS/Linux/WSL)detect.ps1: Scan for structural smells (Windows)
Usage
# Scan a package for squatters
.codex/skills/refactor/squatters/scripts/detect.sh pulsar/api
# Scan with specific pattern focus
.codex/skills/refactor/squatters/scripts/detect.sh pulsar/api --pattern utility-dump
.codex/skills/refactor/squatters/scripts/detect.sh pulsar/api --pattern stuttery-sibling