CH-ZHOU-0512/wiztree-disk-cleaner

WizTree Disk Cleaner

Use WizTree as the source of disk-usage facts and keep analysis, approval, execution, and verification separate. Match the user's language in reports.

Non-negotiable safety gates

• Default to analysis only. Do not mutate the disk while importing or reviewing CSV data.
• Treat Tier 1 as low-risk, not approval-free. Require explicit user approval before every deletion.
• Never infer approval from a general request such as “clean my disk”. Show exact targets and actions first.
• Never run deletion commands copied from model prose. Build a plan with scripts/New-CleanupPlan.ps1, show its plan_id, and execute only after the user confirms that exact plan.
• Reject wildcards, relative paths, drive roots, broad user-profile roots, system directories, program directories, and Tier 3 targets.
• Do not clean a live machine from a CSV exported on another machine. Analyze only unless local path existence and machine scope are established.
• Do not download or install WizTree without the user's request. Do not redistribute the WizTree executable with this skill.
• Use only native PowerShell file operations end to end. Revalidate canonical targets immediately before recursive deletion.

Read references/safety-policy.md before classifying or approving targets. Read references/wiztree-csv.md when exporting or parsing WizTree data.

Workflow

1. Acquire a current CSV

Prefer a CSV exported from the current machine and current disk state.

• If the user already has an export, record its absolute path and timestamp.
• If WizTree is installed and the user wants automation, run scripts/Export-WizTree.ps1.
• Otherwise, instruct the user to scan the target drive in WizTree and use its official CSV export.

Do not use screenshots as the canonical inventory when a CSV export is available.

2. Produce the first report

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/Analyze-WizTreeCsv.ps1 `
  -CsvPath <absolute-csv-path> `
  -OutputDirectory <absolute-report-directory>

Use the generated JSON as machine-readable evidence and the Markdown report as the user-facing record. Copy the structure in assets/cleanup-report-template.md if additional narrative is needed.

Verify these points before recommending cleanup:

• Count allocated bytes from file rows; do not sum nested folder totals.
• Treat hard-link allocated values with WizTree's leading-zero marker as zero additional allocation.
• Distinguish a cache from user-created content merely stored under a cache-like name.
• Mark uncertainty explicitly. Move an item to a higher-risk tier when evidence is incomplete.

3. Investigate Tier 2

Inspect each material Tier 2 candidate before presenting it. Check, when available:

• owning application or Windows component;
• whether the application or service is currently running;
• modification recency and whether files are actively changing;
• whether the application provides its own cleanup command;
• regeneration cost, sign-in impact, offline impact, and recovery options;
• exact path, proposed action, estimated bytes, and expected side effects.

Prefer application-native cleanup, Windows Storage settings, Disk Cleanup, package-manager cache commands, or documented service-aware procedures over raw deletion.

4. Obtain itemized approval

Present Tier 1 first. For every selectable item include:

• exact path;
• action: clear_directory_contents or delete_file;
• tier and reason;
• estimated reclaimable bytes;
• notable side effects.

Create an approval manifest from assets/approval-manifest.example.json. Include only items the user explicitly selected and set approved to true.

5. Preview and bind the plan

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/New-CleanupPlan.ps1 `
  -ApprovalFile <approval-json> `
  -PlanFile <plan-json>

Show the validated items, estimated total, rejected items, and plan_id. Stop if any target is broader than the user's selection or differs from the report.

6. Execute only the confirmed plan

After the user confirms the displayed plan_id, run:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/Invoke-ApprovedCleanup.ps1 `
  -PlanFile <plan-json> `
  -ConfirmPlanId <confirmed-plan-id> `
  -Execute

Without -Execute, the script remains a dry run. Never add -Execute before the exact plan confirmation is visible in the conversation.

7. Verify and update the report

• Record successes, skips, failures, and the audit-log path.
• Record estimated deletion bytes and observed free-space change separately; background activity can make them differ.
• Re-export or rescan WizTree when practical.
• Update the Markdown report's execution history and remaining Tier 2 choices.
• Repeat the approval cycle for Tier 2. Never promote Tier 3 into an executable plan.

Resource map

• scripts/Export-WizTree.ps1: invoke the official WizTree CSV export.
• scripts/Analyze-WizTreeCsv.ps1: stream the export and generate JSON plus Markdown.
• scripts/New-CleanupPlan.ps1: validate selected targets and create an integrity-bound plan.
• scripts/Invoke-ApprovedCleanup.ps1: revalidate and execute the confirmed plan with JSONL audit logging.
• references/safety-policy.md: classification and deletion boundaries.
• references/wiztree-csv.md: official export semantics and parser expectations.
• assets/cleanup-report-template.md: report structure.
• assets/approval-manifest.example.json: approval input schema.