safe-cleanup

name	safe-cleanup
description	Performs one evidence-backed, behavior-preserving source cleanup at a time. Use when the user asks to remove a concrete duplication, dead indirection, oversized responsibility, or similar maintainability problem without changing observable behavior.
license	MIT
compatibility	Pi skill for a trusted writable Git worktree with project-defined verification commands.
metadata	{"version":"1"}

Safe Cleanup

Purpose

Complete exactly one bounded cleanup target while preserving observable behavior. Prefer a small deletion or simplification over a new abstraction, configuration option, framework, or broad rewrite.

This skill provides a workflow, not a repository scanner. Do not import or recreate OMP-specific clone, god-object, dead-export, deep-import, or defensive-check scanners.

Preconditions

Before editing:

1. Read the applicable repository instructions and owner documentation.
2. Inspect the current branch, worktree, and target files. Preserve unrelated and pre-existing changes.
3. Restate one concrete cleanup target and the observable behavior that must remain unchanged.
4. Identify the exact baseline test command. If no meaningful observable check exists, define the smallest one before cleanup.
5. Stop and ask when the target, behavioral contract, authority, or expected verification is ambiguous.

One-target workflow

1. Establish evidence

Use direct inspection and focused search to prove the target exists. Record:

• the duplicated, dead, indirect, or oversized responsibility being removed;
• its owner and active call sites;
• the files that should change;
• explicit non-goals;
• the current worktree state.

Do not turn candidate discovery into a general-purpose scanner or clean adjacent findings.

2. Capture the baseline

Before editing:

1. Run the exact focused test command and record its result.
2. Run any required typecheck, lint, or build check needed to define current behavior.
3. Record the target files' baseline line count or a reproducible Git diff base.
4. If the baseline fails, stop unless the user explicitly scopes the existing failure into the task.

The final verification must rerun the same focused test command, not a weaker substitute.

3. Define the minimal change

Write a compact change statement:

• what will be removed or consolidated;
• which call sites must migrate;
• which public behavior and data shape stay fixed;
• what will not be refactored.

Prefer deletion and direct reuse. Introduce a shared helper only when more than one real caller needs the same behavior and the helper makes the ownership clearer.

4. Implement surgically

• Change only the selected target and required call sites.
• Keep implementation and focused tests together.
• Match existing style and public contracts.
• Do not rename unrelated identifiers, reformat nearby files, add speculative options, or improve adjacent code.
• Remove imports, exports, variables, and files made unused by this cleanup.
• When migration starts, complete every in-scope call site before verification.

5. Verify behavior and completeness

After editing:

1. Rerun the exact baseline test command.
2. Rerun the applicable typecheck, lint, build, and package checks.
3. Search for stale references to the removed path, helper, export, or call pattern.
4. Inspect the complete diff for accidental behavior, API, formatting, dependency, or generated-file changes.
5. Run git diff --check when Git is available.
6. Report added lines, deleted lines, and net LOC delta from a reproducible diff.
7. Confirm unrelated pre-existing worktree changes remain untouched.

A passing test is necessary but not sufficient: call-site migration and diff inspection must also be complete.

Required report

Return a compact report with:

• Target: the one cleanup completed;
• Behavioral contract: what stayed unchanged;
• Changed files: exact repository-relative paths;
• Baseline: exact commands and outcomes before editing;
• Final verification: the same commands and outcomes after editing, plus additional checks;
• Migration evidence: how stale call sites or exports were ruled out;
• LOC delta: added, deleted, and net lines;
• Residual risks: anything not verified;
• Non-goals preserved: adjacent findings intentionally left alone.

Do not claim behavior preservation when baseline and final commands differ, verification could not run, or stale call sites remain possible.

Stop conditions

Stop and ask rather than broadening the task when:

• the baseline test fails;
• the same failure remains after one evidence-backed fix;
• cleanup requires a public API, schema, dependency, authority, or product decision;
• dynamic or external call sites cannot be bounded;
• fixing one area requires unrelated migrations;
• the diff grows beyond the stated target;
• the next attempt would be another guess instead of a new testable hypothesis.

Do not commit, push, publish, install, or modify user configuration unless the user separately authorizes that action.