Code Service Defrag

Code + Service Defrag

Periodic consolidation of a fragmenting codebase — code AND context — back into coherent, single-source-of-truth wholes. The maintenance discipline that counteracts the entropy agentic coding produces.

Meta-Principle: Agentic coding fragments state faster than humans consolidate it. Fragmentation only accumulates — it is the second law applied to repos. Defrag is the periodic counter-force. Run it on a cadence, or discover the fragmentation the day a deploy fires from the wrong directory.

Why Fragmentation Is Inevitable (it is not a failure)

Conway's Law says a system mirrors the communication structure of whoever built it. Invert it: a codebase touched by parallel agents and multiple humans across many sessions — with no single mind holding the whole map — necessarily accumulates fragments. Duplicate configs, forks, orphan specs, services quietly sharing a database. This is not sloppiness to feel bad about; it is the expected entropy of high-leverage, multi-actor development. The only real question is whether you defrag periodically or meet the fragmentation when it detonates.

The leverage of agentic coding (ship 10x faster) is paid for in visibility (nobody holds the full map). Defrag buys the visibility back, cheaply, on a schedule.

Two Terrains Fragment in Parallel

Treat both as first-class. Code drift fails loud (eventually — when a deploy detonates). Context drift fails silent — an agent reads the wrong spec, produces confidently wrong work, and nobody notices until it ships. The context half of this skill is not a footnote to the code half; it is the half that fails without a stack trace.

The Collision Shape (universal across platforms)

Any system with multiple deployable units accumulates collision risk: two things that can silently overwrite or corrupt each other. The platform changes the vocabulary, not the shape.

The landmine is always the same shape: two configs name the same target, or bind the same shared resource, and the platform does not stop the wrong one from winning. Whether that shape is 🔴 or 🟢 depends on the platform's deploy model — see references/platform-collision-semantics.md. A name match is a candidate, never an automatic verdict.

Perceived vs Actual Problem

Fragmentation registers as a vague "things are getting messy in here" unease. A vague feeling is not actionable, so it gets deferred — until it detonates. Defrag's core move is converting the unactionable feeling into a specific, located, severity-ranked finding.

If a defrag pass ends with a feeling instead of a located finding with a file path and a severity, it failed.

The Three Tests (apply to any candidate)

These are the teeth. Run them before classifying severity.

1. The "Which one is live?" test. For every deploy-target name, can you name the canonical directory in under five seconds? Hesitation is the finding — your mental map has diverged from the repo. A system you can't answer this for instantly is already fragmented.

2. The "Two-deploy" test. If you ran the deploy command from each directory sharing a target name, would the same live deployment change? Yes → they are the same target; one is a silent-overwrite landmine (🔴). No (different platform/project/namespace) → coincidental (🟢). This test is what platform-collision-semantics.md formalizes per platform.

3. The "Onboard cold" test (context). If a fresh agent loaded context for this project right now, would it find one coherent source — or land in whichever fragment it happened to hit first? More than one possible answer = context fragmentation, even if every individual doc is fine.

When to Apply This Skill

Apply when:

• Periodic: last defrag >30 days ago (the discipline — don't wait for a trigger)
• Pre-deploy: before any deploy / push / release on a shared account
• Post-migration: immediately after a repo merge, git subtree add, directory move, or fork consolidation
• Post-multi-agent work: after parallel agents create parallel fragments
• On-demand: when canonical-source ambiguity is suspected ("which one is the real one?")
• On confusion: when someone catches themselves saying "I thought I deleted that" or "didn't we consolidate that?"

Do NOT apply when:

• Starting a greenfield project with no existing multi-service layout
• Auditing knowledge base branches (use a KB-specific audit instead)
• Auditing a single app's internal structure (use a general code-review/simplify pass)
• Fixing is already planned and scoped — skip to the migration step

Detect-Only, Never Auto-Fix

The skill produces a severity-ranked report; the human decides what to consolidate. Auto-fixing would re-introduce the exact cowboy problem this skill exists to prevent — one more actor changing state without holding the whole map. Defrag's job is to restore visibility, not to act on it unsupervised.

Workflow

Step 1: Establish Scan Scope

Default scope: apps/* (or services/, packages/) in the current repo — any directory holding deployable units with their own configs.

# List app-like directories
ls -d apps/*/ services/*/ packages/*/ 2>/dev/null

# Spot deployable units across platforms
find . -maxdepth 3 \( -name "wrangler.toml" -o -name "railway.json" -o -name "railway.toml" \
  -o -name "vercel.json" -o -name "fly.toml" -o -name "render.yaml" \
  -o -name "docker-compose.yml" -o -name "Dockerfile" \) -not -path "*/node_modules/*" 2>/dev/null

Confirm scope with the user if ambiguous.