path: root/skills/exterminate-slop/SKILL.md

---
name: exterminate-slop
description: "Perform an exhaustive language-aware subtree audit for primitive obsession, under-abstraction, duplicated logic, defensive ceremony, and code-volume bloat. Use when Codex needs to inspect every source file in a requested scope, keep a persisted worklog/ledger, and produce a long, comprehensive, prioritized defect report that is directly executable as an implementation specification."
---

# Exterminate Slop

Read the target repo's AGENTS.md files first.

This is a slop extermination audit, not a style review. The objective is to identify every material opportunity to crush code volume and ceremony while increasing semantic density, then write a standalone prioritized defect report precise enough to execute. Preserve externally observable behavior unless the user explicitly asks for behavior change. Do not preserve backward compatibility by default.

## Language Lens

Before the first source read, determine the dominant implementation language for the requested scope and read exactly one note:

- Rust: [references/languages/rust.md](references/languages/rust.md)
- Java: [references/languages/java.md](references/languages/java.md)
- Python: [references/languages/python.md](references/languages/python.md)
- TypeScript: [references/languages/typescript.md](references/languages/typescript.md)

If the scope truly crosses language boundaries, start with the dominant language and load a second note only when the report or implementation must cross that boundary. If no note exists for the dominant language, proceed with this generic core and record the missing note in the worklog.

## Contract

- Require a concrete source subtree. If the user names only a repo, choose the smallest plausible subtree and state the assumption.
- Default to `defect_report`. Execute code changes only when the user explicitly asks for implementation.
- Build a full manifest of in-scope source files for the chosen language. No sampling and no "representative files."
- Exclude generated, vendored, build-output, fixture, snapshot, and dependency files unless the user explicitly includes them.
- Create one persistent `/tmp` worklog before the first source read. Chat is summary only; the worklog is the durable source of truth.
- Create one standalone `/tmp` defect report as the terminal artifact of the default pass.
- Take a cheap code-volume baseline for the manifest. At minimum count lines; token count is welcome when cheap.
- Partition the manifest into intentional logical cliques before deep reading.
- Read at most 8 files per wave.
- Write a `/tmp` checkpoint after every wave before reading more files.
- Record raw suspects during coverage, then promote only threshold-clearing suspects into the formal ledger after full coverage.
- Force a decision and priority on every promoted ledger row.
- Do not edit source during `defect_report` mode. If implementation is requested, write the defect report first, then execute from it in priority/dependency order.
- Re-scan the manifest when implementation occurs and record residual slop plus code-volume delta.

Files may be re-read. Re-reading is expected when a file belongs to multiple logical cliques or when a later duplication cluster changes the correct abstraction boundary.

## Flow

### 0. Create The Worklog

Create paths shaped like:

```text
/tmp/exterminate-slop-<repo-or-dir>-<subtree-slug>.md
/tmp/exterminate-slop-<repo-or-dir>-<subtree-slug>-defect-report.md
```

Seed the worklog with the skeleton below.

The worklog must hold the language lens, manifest, volume baseline, clique plan, wave checkpoints, rejected clusters, promoted ledger, defect report path, implementation batches if any, verification if any, residual sweep if any, and volume delta if any.

If interrupted or resumed, reopen the same worklog before continuing.

### 1. Lock Scope And Manifest

Enumerate the full source manifest using the loaded language note. Examples:

```bash
rg --files <subtree> -g '*.rs'
rg --files <subtree> -g '*.java'
rg --files <subtree> -g '*.py'
rg --files <subtree> -g '*.ts' -g '*.tsx' -g '*.mts' -g '*.cts'
```

Persist the manifest and baseline immediately. If the note gives different inclusion rules, follow the note.

### 2. Plan Logical Cliques

Before deep reading, group manifest files into small logical cliques.

Good clique causes:

- shared domain concepts or latent domain objects
- repeated parse, validate, normalize, or coercion flows
- repeated rendering, formatting, serialization, or transport mapping
- repeated construction, patch, query, or conversion logic
- repeated control-flow skeletons
- parameter clumps, field bundles, or option bags crossing boundaries
- module-boundary interactions
- suspected duplication clusters

Cliques may overlap. A file may appear in multiple cliques. Keep cliques to 2-8 files; split larger conceptual groups into multiple related waves.

### 3. Run Coverage Waves

For each clique wave:

- read at most 8 files
- use the language's semantic navigation tools aggressively when available
- anchor from live use sites before declaration spelunking
- update manifest coverage
- write a checkpoint containing:
  - clique id and purpose
  - files inspected
  - raw suspects
  - duplication hypotheses strengthened or weakened
  - files worth re-reading in later cliques
  - abstraction pressure
  - code-volume pressure

Do not read a 9th file until that checkpoint exists. A file counts as covered once it has been read in at least one wave.

### 4. Run Smell Passes

Run distinct passes over the manifest and checkpointed suspects. If a pass needs more context, form another clique and respect the 8-file cap again.

#### Primitive Semantics

Interrogate strings, numbers, booleans, nulls, sentinels, loose maps, loose objects, tuple-ish sequences, and raw identifiers. Ask whether the value is really an id, slug, path, URL, unit, currency, status, mode, phase, capability, policy, timestamp, validated token, finite world, or richer domain object.

#### Bundles And Bags

Interrogate tuples, argument clumps, option bags, repeated object shapes, repeated field bundles, parallel collections, public optional walls, and correlated primitive sets. Ask whether the same values travel together, whether invalid states are currently representable, and whether one named representation would delete the surrounding ceremony.

#### Duplication And Under-Abstraction

Search for repeated parse, validate, normalize, default-fill, render, serialize, authorize, query, convert, patch, compare, and error-shaping logic. Search for branch skeletons with only small local differences. Treat DRY as stronger than YAGNI.

#### Defensive Theater

Interrogate checks, wrappers, fallbacks, compatibility shims, exception laundering, nil/null/undefined handling, default values, and "safe" access paths. If static structure, construction flow, or local dominance proves the value exists, delete the ceremony. If the fallback has no honest semantics, fail fast.

#### Code-Volume Bloat

Interrogate code whose main sin is existing: pass-through layers, one-line wrappers, adapter twins, DTO mirrors, getter/setter husks, scattered casts, repeated fixtures, duplicated builders, commented-out compatibility, and explanatory locals that only compensate for weak structure. The pass has an explicit line/token reduction objective.

### 5. Promote Suspects

During coverage, keep only raw suspects. After every manifest file has been inspected at least once, promote a suspect into the formal ledger only if at least one is true:

- it appears in more than one file or module
- it crosses a meaningful boundary
- it shows invariant pressure rather than cosmetic repetition
- it deletes code volume while preserving or strengthening semantics
- the fix is locally actionable now

Anything not promoted must still be accounted for as a short rejected cluster. Persist both promoted and rejected outcomes in the worklog.

### 6. Populate And Adjudicate The Ledger

Populate the formal ledger with one row per promoted candidate.

Allowed `kind` values:

- `primitive_semantics`
- `weak_type`
- `boolean_mode`
- `tuple_or_sequence`
- `clump_or_bag`
- `duplicate_logic`
- `primitive_control_encoding`
- `defensive_theater`
- `ceremonial_layer`
- `volume_bloat`

Allowed `priority` values:

- `P0`: systemic invariant failure, severe duplication contagion, or high-confidence volume collapse that should dominate the implementation plan
- `P1`: substantial local or cross-module payoff with a clear implementation shape
- `P2`: real defect with moderate payoff, narrower blast radius, or dependency on higher-priority cleanup
- `P3`: valid but marginal, risky, or best recorded as residual work

Allowed `decision` values:

- `specify_now`
- `defer`
- `false_positive`
- `needs_broader_design`

For every row, choose exactly one priority and one decision. The ledger is authoritative even if chat shows only a condensed view.

### 7. Write The Defect Report

Write the standalone defect report after the promoted ledger exists. It must be long, comprehensive, prioritized, and directly executable. Do not merely dump the ledger; synthesize it into an implementation specification.

Use this shape:

```markdown
# Exterminate Slop Defect Report: <scope>

## Executive Summary

Summarize inspected scope, language note, manifest coverage, dominant slop patterns, and the top defects.

## Scope And Method

- scope root
- language note
- manifest size
- excluded surfaces
- clique-wave summary
- worklog path
- volume baseline

## Priority Order

| priority | defect_id | title | kind | confidence | blast_radius | expected_payoff | dependencies |
|----------|-----------|-------|------|------------|--------------|-----------------|--------------|

## Defects

### <priority> <defect_id>: <title>

**Kind:**  
**Priority:**  
**Confidence:**  
**Sites:**  
**Evidence:**  
**Why This Is A Defect:**  
**Proposed Shape:**  
**Implementation Specification:**  
**Behavior Preservation:**  
**Verification:**  
**Expected Code-Volume Effect:**  
**Risks / Edge Cases:**  
**Depends On / Blocks:**  

## Rejected Clusters

Account briefly for suspects that did not deserve implementation.

## Execution Notes

Give recommended implementation order, batching boundaries, and pre-edit checks.

## Residual Unknowns

Record only real uncertainty, not generic caution.
```

Implementation specifications should describe the semantic move, files/sites affected, expected abstraction boundary, behavior-preservation obligations, and verification surface. They should be precise enough for an implementer to act without rerunning the audit from scratch.

### 8. Optional Execution

If the user explicitly asked for implementation, execute from the defect report in priority/dependency order after the report exists.

Group work by semantic move:

- primitive semantics → domain type, literal world, enum, opaque/branded type, value object, validated constructor, or parser boundary
- primitive control encoding → closed variant, state type, policy object, dispatch table, or sealed/discriminated hierarchy
- tuple or clump → named domain object with the invariant in one place
- loose bag → precise typed record, variant, or boundary DTO converted immediately
- duplicate logic → one owner function, constructor, trait/protocol/interface, table, macro, generator, or module
- defensive theater → static proof, fail-fast access, or single boundary check
- volume bloat → deletion, fusion, abstraction, or mechanical modernization

Prefer the clean shape over compatibility. Apply the language note's sharper moves where it speaks.

After edits, run relevant checks on the touched surface, re-scan the same manifest, measure code-volume delta, and update the worklog with eliminated rows, deferred rows, false positives, residual hotspots, verification, and volume results.

Prefer the narrowest checks that still validate the changed surface, then widen if needed.

## Embedded Forms

### Worklog Skeleton

```text
worklog_path:
defect_report_path:
scope_root:
mode: defect_report | defect_report_then_execute
language:
language_note:
wave_size_limit: 8

volume_baseline:

manifest:

clique_plan:

wave_checkpoints:

rejected_clusters:

promoted_ledger:

report_summary:

implementation_batches:

verification:

residual_sweep:

volume_after:
volume_delta:
```

### File Manifest

```text
scope_root:
mode: defect_report | defect_report_then_execute
language:
language_note:
wave_size_limit: 8

files:
- [ ] path/to/file_a
- [ ] path/to/file_b
- [ ] path/to/file_c
```

Rules:

- include every source file in the requested subtree for the selected language
- mark files as inspected only after reading them
- allow files to appear in multiple clique waves
- do not delete rows from the manifest during implementation
- use the same manifest again for the residual sweep if implementation occurs

### Clique Wave Checkpoint

```text
clique_id:
purpose:
why_these_files_belong_together:
wave_size:

files:
- path/to/file_a
- path/to/file_b

checkpoint:
- raw suspects:
- duplication hypotheses:
- likely rereads:
- abstraction pressure:
- code-volume pressure:
```

Rules:

- `wave_size` must never exceed `8`
- write a checkpoint into the worklog after every wave before reading more files
- keep the checkpoint terse and raw; do not inflate every suspect into a formal ledger row yet
- name the clique by the suspected relationship, not by arbitrary adjacency

### Rejected Cluster

```text
cluster_id:
kind:
sites:
- path/to/file_a :: short note
- path/to/file_b :: short note

rejection_reason:
still_watch_for:
```

Good rejection reasons:

- boundary-shaped transport code
- serialization or protocol surface where primitive form is correct
- cosmetic repetition without invariant pressure
- local-only pattern with no cross-site duplication
- abstraction name still too foggy to justify extraction

### Promoted Ledger

```text
| defect_id | priority | path | symbol_or_site | kind | evidence | proposed_shape | duplication_cluster | volume_effect | confidence | implementation_order | decision | decision_reason |
|-----------|----------|------|----------------|------|----------|----------------|---------------------|---------------|------------|----------------------|----------|-----------------|
| S001 | P1 | src/foo | User.id: string | primitive_semantics | parsed, validated, and compared in 3 places | UserId domain type | id-handling-1 | deletes repeated validation | high | 1 | specify_now | domain identifier with repeated normalization |
| B001 | P1 | src/bar | run(..., dryRun: boolean) | boolean_mode | positional flag controls strategy | ExecutionMode variant | mode-flags-1 | removes branch duplication | high | 2 | specify_now | bool hides a mode split |
| D001 | P0 | src/baz | copy/update loop | duplicate_logic | same field-by-field patch in 4 sites | owned patch function | patching-2 | deletes 40 lines | medium | 0 | specify_now | one owner is obvious |
```

Requirements:

- `evidence` must name the concrete smell, not a vague feeling
- `proposed_shape` must be specific
- `volume_effect` must state deletion/compression potential when relevant
- `duplication_cluster` must group related rows when applicable
- `implementation_order` must respect dependencies, not merely priority labels
- `decision_reason` must explain why the row did or did not graduate into the report
- do not create rows for suspects that failed promotion; summarize those as rejected clusters instead

## Adjudication Checklist

For every ledger row, ask:

- Does this primitive or shape carry domain semantics rather than mere transport?
- Are invalid states representable today?
- Does validation, normalization, parsing, formatting, or defaulting repeat?
- Do correlated values drift apart because no one object owns them?
- Does this cross a boundary where the weak shape becomes contagious?
- Would a stronger type or abstraction delete nearby code?
- Is the abstraction name sharp enough to carry the invariant?
- Can the fix be specified locally, or does it require a broader design cut?

Decision mapping:

- `specify_now`: the abstraction is clear and actionable enough for the defect report
- `defer`: the smell is real but the present specification would be premature
- `false_positive`: the shape is genuinely incidental or boundary-correct
- `needs_broader_design`: the smell is real but the right abstraction spans a larger domain cut

## Final Response

Always include:

- the `/tmp` worklog path
- the `/tmp` defect report path
- language note used
- manifest coverage summary
- clique-wave summary
- rejected-cluster summary
- promoted-ledger summary
- priority summary
- volume baseline and expected code-volume payoff

If you edited code because implementation was explicitly requested, also include:

- abstraction batches executed
- verification summary
- residual sweep summary
- actual volume delta

## Hard Failure Modes

- do not inspect only "important" files
- do not skip the `/tmp` worklog or keep checkpoint state only in chat
- do not omit the standalone defect report
- do not read more than 8 files without a persisted checkpoint
- do not silently compact a wave because you feel you "basically got it"
- do not treat one clique as if it exhausts all duplication relationships
- do not promote everything into the formal ledger just to feel exhaustive
- do not drop non-promoted suspects on the floor; summarize them as rejected clusters
- do not edit source in `defect_report` mode
- do not propose generic cleanup without row-level evidence
- do not preserve compatibility unless the user asked for it
- do not let tests, lint, or formatters substitute for the extermination pass