ops-clean git:20260903.280fae3A

Immutable. This exact content never changes and is served at /api/v1/blob/8cc7ca987825e8ed.

---
name: ops-clean
description: "Remove accumulated repository debt across design, code, tests, dependencies, scripts, docs, assets, structure, and generated residue."
---

## OBJECTIVE

Reduce accumulated project complexity and maintenance cost while preserving the accepted product contract.

`dev-chore` catches bounded quality drift during active development. `ops-clean` handles repository-wide debt that has already accumulated: duplicate implementation, wrong abstractions, hand-rolled wheels, misleading tests, dead scripts, temporary files, stale dependencies, structural clutter, and documentation or generated residue.

## INPUT

```text
ops-clean [target]
  [--domain design|code|tests|dependencies|scripts|docs|assets|structure|generated|all]
  [--mode inspect|plan|apply]
  [--depth quick|standard|deep]
```

Defaults: `--domain all --mode apply --depth standard` when the user requests cleanup; otherwise inspect only.

## CONTRACT GATE

Before deleting or consolidating:

- state the current maturity and user-visible contract;
- identify the real build, test, package, and runtime entry points;
- preserve unrelated dirty work;
- establish the cheapest relevant baseline;
- distinguish tracked source, generated output, ignored local state, and external/vendor content.

If a cleanup would intentionally change supported behavior, public contracts, persistent data, or architecture, route that item through `dev-fix`, `dev-refactor`, or an architecture workflow. Do not hide a redesign inside hygiene work.

## NET SIMPLIFICATION GATE

A successful apply must make the preserved behavior easier to own, not merely rearrange it.

- Name the concrete owner, implementation, layer, dependency, configuration axis, script, test framework, or failure mode being removed or consolidated.
- Prefer deletion and consolidation before rewriting. A new abstraction is justified only when it replaces existing concepts or is required to preserve the accepted contract.
- Compare before and after with concrete nouns; do not invent a complexity score or optimize raw line count.
- Do not claim simplification for renames, moves, formatting, or added wrappers that leave the same responsibilities and failure modes in place.
- Run the real primary path after behavior-adjacent simplification.

## QUALITY DOMAINS

### Design

- A known-wrong premise that later code keeps patching around.
- Abstractions, layers, services, adapters, factories, compatibility paths, flags, or configuration axes with no current requirement.
- Multiple owners or sources of truth for the same state or decision.
- Production or enterprise machinery imposed on prototype, MVP, or core scope without evidence.

### Code

- Duplicate implementations, parallel utilities, copied logic, dead branches, unreachable paths, and obsolete compatibility code.
- Wrapper layers that add names but no policy, transformation, isolation, or reuse.
- Hand-built parsing, scheduling, storage, protocol, security, or domain logic when the existing stack or a proven library already solves the requirement.
- Comments, defensive branches, and error paths that describe impossible states or conceal unclear ownership.

### Tests

- Tests that cannot catch the defect they claim to cover.
- Tautological assertions, implementation-copy oracles, mock-only boundary proof, unjustified substitutes, skipped/xfail residue, flaky tests, duplicate cases, and snapshots no one can review.
- Test-only helpers or fixtures that outlive all consumers.
- Broad test frameworks whose maintenance cost exceeds the behavior they protect.

Do not delete a failing test merely because its product behavior is inconvenient. Resolve whether the contract or implementation is wrong.

### Dependencies

- Unused, duplicated, abandoned, unpinned, vulnerable, or unjustifiably heavy packages.
- A local wheel that should be replaced by an existing dependency.
- A dependency that should be replaced by a small local implementation.

Before adding or replacing a dependency, compare maintenance, license, advisories, install scripts or native code, transitive footprint, compatibility, API fit, and lockfile impact. Popularity alone is not proof, and dependency replacement must reduce total complexity.

### Scripts and Tooling

- One-off investigation scripts, temporary migrations, debug launchers, stale generators, duplicate CI helpers, and commands no real workflow calls.
- Tooling that reproduces an ecosystem command without project-specific value.
- Formatter, linter, or build configurations that overlap or fight the repository's actual gate.

### Docs and Assets

- Stale, contradictory, duplicated, generated, placeholder, or assistant-residue documentation.
- Unreferenced images, media, samples, reports, archives, and copied vendor material.
- Names and locations that obscure ownership or the canonical source.

### Structure and Generated State

- Empty directories, abandoned modules, old migrations, temp files, caches, coverage output, packaged archives, editor debris, and generated files committed without a repository contract.
- Build outputs or host distributions that should be regenerated rather than hand-edited.
- Local agent state accidentally tracked as project source.

## METHOD

1. **Inventory cheaply.** Use manifests, dependency graphs, references, imports, build scripts, test discovery, package contents, and version-control history before reading every file.
2. **Find ownership.** For each candidate, identify its producer, consumers, replacement, and user-visible effect.
3. **Choose an action.**

```text
keep | simplify | consolidate | replace | move | delete | defer
```

4. **Order by leverage.** Remove wrong foundations and duplicate ownership before polishing leaves.
5. **Apply in reviewable batches.** One coherent concern per batch; re-run the cheapest rejecting check after each.
6. **Regenerate owned outputs through the canonical producer.**
7. **Run the relevant repository gates and one real primary workflow when behavior-adjacent code changed.**

Deletion evidence may be imports/references, runtime discovery, package manifests, generated ownership, history, and focused probes. Absence from one text search is not sufficient when reflection, plugins, generated registration, or external consumers are possible.

## STOP CONDITIONS

Stop and use `ops-ask` when:

- two artifacts appear to own the same contract but the canonical owner is unclear;
- removal changes a public or persistent contract;
- a proposed replacement introduces a material dependency or architecture decision;
- dirty work overlaps the cleanup target and cannot be preserved;
- the current design is so compromised that bounded cleanup is more expensive than a respawn assessment.

Use `ops-nuke` only for the last case after the user explicitly selects a full respawn.

## OUTPUT

```markdown
## Contract
- Maturity:
- Preserved behavior:
- Domains:
- Baseline:

## Actions
| Item | Evidence | Action | Effect | Check |
| --- | --- | --- | --- | --- |

## Deferred
- Item:
- Missing evidence or required decision:

## Result
- Removed or consolidated:
- Complexity reduced:
- Checks:
- Real workflow:
```

`ops-clean` does not commit, distribute, publish, deploy, or replace the default branch unless the user separately requests that workflow.