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.

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026

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.
namerefactor-squatters
licenseMIT
description|
Detect squattersmodules and packages that occupy namespace positions
authorJordan 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:

  1. Agentic programming prioritizes "make it work" over "make it belong"
  2. Domain modeling was deferred — the code landed somewhere expedient
  3. Compensatory naming masked the misplacement (e.g., las_fields.py instead of las/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/, or helpers/ packages
  • Seeing modules with underscore prefixes matching sibling package names (e.g., las_fields.py beside las/)
  • 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 accomplishes
  • 02_DEFINITIONS.md — Vocabulary for squatters and namespace violations
  • 03_INVARIANTS.md — Rules that determine violations
  • 04_HEURISTICS.md — Detection patterns and signals
  • 05_PROCEDURE.md — Step-by-step audit process
  • 06_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