jordangunn/refactor-squatters
skills/refactor/squatters/SKILL.md
Detect squatters: modules and packages that occupy namespace positions they do not semantically own. Identifies utility dumps, stuttery siblings, axis violations, layer bleeding, and semantic diffusion — common structural smells introduced by agentic programming.
$ install --global
skillsauthnpx skillsauth add jordangunn/skills refactor-squattersInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 6, 2026, 10:25 AM188.5s10 files scanned
SKILL.md
- 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
Related Skills
jordangunn/task-validate
testing
VerifiedTrustedCommunity
Validate a task by setting epistemic_state to validated. Requires explicit validation info (who/why). Computes hash and updates last_reviewed_at.
6SKILL.mdUpdated Apr 6, 2026
jordangunn/task-status
tools
VerifiedTrustedCommunity
Compute and display derived status for a task. Runs deterministic status computation and outputs summary of staleness, hash integrity, and eligibility.
6SKILL.mdUpdated Apr 6, 2026
jordangunn/task-review
tools
VerifiedTrustedCommunity
Review a task by updating last_reviewed_at timestamp. Recomputes derived status and flags any hash mismatches without changing epistemic state.
6SKILL.mdUpdated Apr 6, 2026
jordangunn/task-prev
testing
VerifiedTrustedCommunity
Navigate to the previous task in chronological order. Returns the task ID before the specified task based on created_at timestamp.
6SKILL.mdUpdated Apr 6, 2026