Reversible Cleanup Planner

Plans and stages filesystem cleanups safely. Generates inventory lists, calculates reclaimable space, moves candidates to a reversible staging trash folder, and provides an immediate rollback command. Never runs destructive rm -rf directly.

1. Purpose

Safely reclaim disk space without risk of accidental data loss. "Reversible cleanup" moves candidate files to a staged .trash_staging folder first, giving operators time to verify system stability before final purge.

2. When to Use

Use this skill when:

• Freeing disk space from old logs, temp files, test artifacts, or build caches.
• Preparing a cleanup routine for a cluttered workspace.
• User requests: "Clean up temp files" or "Free disk space in this folder."

3. When Not to Use

• Do not use for code refactoring; use small-refactor.
• Do not use for database table cleanup; use task-brief.

4. Required Inputs

• target_directory: Directory path to clean up.
• cleanup_criteria: Glob pattern, file age, or file extension (e.g. *.tmp, *.log older than 14 days).

5. Missing-Input Behavior

1. If target_directory is missing: stop and ask for the target directory.
2. If target_directory is root (/) or home directory (~): halt immediately and refuse. Target directory must be a specific subfolder.
3. Never use rm in the staging phase; always use mv to a staging area.

6. Procedure

Follow these numbered actions:

1. Action 1: Execute Dry Run & Inventory
   • Run companion dry run script:

     python3 skills/reversible-cleanup-planner/scripts/dry_run_cleanup.py <target_dir> --pattern <pattern> --json

2. Action 2: Verify Matches
   • Inspect the file list to confirm no source code or configuration files are matched.
3. Action 3: Prepare Staging Command
   • Construct move command into <target_dir>/.trash_staging/.
4. Action 4: Prepare Rollback Command
   • Construct reverse move command to restore files from staging back to original location.
5. Action 5: Emit Cleanup Plan
   • Format per Section 8.

7. Decision Rules

• If matched files include .git, .env, *.go, *.ts, *.py, *.json: immediately abort cleanup. Exclude protected extensions.
• Require explicit user confirmation before executing any move command.

8. Output Format

Emit the cleanup plan using this template:

### Reversible Cleanup Plan: [Target Directory]

- **Target Directory**: `[Directory]`
- **Filter Pattern**: `[Pattern]`
- **Matched Files**: [Count]
- **Reclaimable Space**: [Bytes / MB]
- **Staging Location**: `[Target]/.trash_staging`

#### Matched File Inventory (Sample)
- `[File 1]` ([Size])
- `[File 2]` ([Size])

#### Stage 1: Safe Reversible Move (Dry Run Verified)
```bash
mkdir -p [Target]/.trash_staging && mv [Target]/[Pattern] [Target]/.trash_staging/

Emergency Rollback Command

mv [Target]/.trash_staging/* [Target]/ && rmdir [Target]/.trash_staging

Stage 2: Permanent Purge (Only after verification period)

# Execute only after 24h stability verification:
rm -rf [Target]/.trash_staging

## 9. Verification Checklist
- [ ] Dry run was performed using [dry_run_cleanup.py](./scripts/dry_run_cleanup.py) or safe list.
- [ ] No source code or config files are in the inventory.
- [ ] Reversible staging step is provided before permanent deletion.
- [ ] Exact rollback command is included.

## 10. Common Failures and Recovery
| Failure Symptom | Cause | Recovery Action |
| :--- | :--- | :--- |
| Overly broad pattern (`*`) | Matching source files | Restrict pattern to specific extension (e.g. `*.tmp`). |
| Accidental immediate deletion | Running `rm` directly | Mandate two-step move to staging trash directory. |

## 11. Stop or Escalation Conditions
Stop and ask the user when:
- Target path contains system directories (`/etc`, `/usr`, `/var`, `/bin`, `/`).

## 12. Examples

### Example 1: Successful Execution
**Input:**
```text
Target: /app/logs
Pattern: *.log
Dry run: 14 files found, 12.4 MB total

Output:

### Reversible Cleanup Plan: /app/logs

- **Target Directory**: `/app/logs`
- **Filter Pattern**: `*.log`
- **Matched Files**: 14
- **Reclaimable Space**: 12.4 MB
- **Staging Location**: `/app/logs/.trash_staging`

#### Matched File Inventory (Sample)
- `app-2026-08-01.log` (2.1 MB)
- `app-2026-08-02.log` (1.8 MB)

#### Stage 1: Safe Reversible Move (Dry Run Verified)
```bash
mkdir -p /app/logs/.trash_staging && mv /app/logs/*.log /app/logs/.trash_staging/

Emergency Rollback Command

mv /app/logs/.trash_staging/* /app/logs/ && rmdir /app/logs/.trash_staging

Stage 2: Permanent Purge

# Run only after confirming application operates normally without logs:
rm -rf /app/logs/.trash_staging

### Example 2: Ambiguous or Missing Input
**Input:**
```text
Target: /
Pattern: *

Output:

### Reversible Cleanup Plan: REFUSED - Unsafe Target

- **Status**: Halted / Safety Boundary Triggered

Cleaning the root directory `/` with pattern `*` is destructive and strictly forbidden. Please specify a safe, bounded application cache or temp directory (e.g. `/tmp/cache` or `./build_artifacts`).

Example 3: Expected Final Output

Output:

### Reversible Cleanup Plan: /workspace/tmp

- **Target Directory**: `/workspace/tmp`
- **Filter Pattern**: `*.tmp`
- **Matched Files**: 5
- **Reclaimable Space**: 450 KB
- **Staging Location**: `/workspace/tmp/.trash_staging`

#### Stage 1: Safe Reversible Move
```bash
mkdir -p /workspace/tmp/.trash_staging && mv /workspace/tmp/*.tmp /workspace/tmp/.trash_staging/

Emergency Rollback Command

mv /workspace/tmp/.trash_staging/* /workspace/tmp/