Why BranchPy does not auto-delete files

Every tool that can delete files faces a design question that sounds simple but isn't: how much should it do on its own, versus how much should it ask you first?

For BranchPy, the answer was settled early and has stayed consistent: the tool does not delete anything you haven't explicitly selected and confirmed. There is no auto-clean, no "remove all unused" button, no background sweep. This note explains why.

The asymmetry problem

When a tool makes a mistake on a read operation — say, it misclassifies a file — the cost is low. You see the wrong label, you notice, you move on. Nothing is lost.

When a tool makes a mistake on a write or delete operation, the cost is potentially permanent. Deleted project files may not be recoverable. Artists' original assets, custom GUI graphics, hand-tuned audio mixes — these aren't always under version control, and they aren't always backed up. For many indie developers working on a first title, there is no safety net.

This asymmetry — where errors in one direction are cheap and errors in the other are catastrophic — changes how a tool should behave by default. The aggressive path only needs to be wrong once.

What "auto-delete" would actually require

For a bulk or automatic delete to be safe, several conditions would all need to be true simultaneously:

1. The scanner's reference analysis would need to be complete — no dynamic references, no engine-loaded paths, no assets used by plugins or custom screens the scanner hasn't seen.
2. The classification would need to be correct for every file in the set.
3. The user's project structure would need to match what the scanner expects — no unusual directory layouts, no conditional loading, no assets referenced only in templates or generated code.
4. The user's working copy would need to be in a recoverable state — version controlled, or backed up, or at minimum tolerant of permanent loss.

In practice, none of these conditions are guaranteed, and the last one is outside the tool's control entirely. A scanner that auto-deletes is betting all four conditions hold for your project, right now, without asking.

The specific case of Ren'Py projects

Ren'Py projects add another layer of complexity. The engine loads many assets through mechanisms that don't appear in script files at all — GUI variables, config.* assignments, font definitions, and built-in screen styles. A file can be genuinely critical to your game launching correctly while appearing completely unreferenced to a script-level scanner.

BranchPy maintains a classification layer specifically for this: files that fall under engine-managed paths are marked PROTECTED before results are ever shown. They cannot be selected. But protection rules only cover what we know about. For everything else in the unreferenced set, the user's review is not a bureaucratic step — it's genuine risk reduction.

The staged approach

What BranchPy does instead of auto-delete is a staged workflow:

1. Scan — enumerate all media files in the project tree.
2. Classify — assign each file a status: referenced, unreferenced, missing, or protected.
3. Present — surface the classified results in a reviewable UI, with reasons visible per file.
4. Confirm — require explicit selection and a confirmation step before any deletion occurs.

Each stage is independent. A problem in classification doesn't silently trigger deletion. A UI bug that rendered the wrong file as selectable would still be caught by the confirmation step. The stages are defence-in-depth for a destructive operation.

What this costs, and why it's worth it

The honest answer is: requiring review costs time. If you have 200 unreferenced files and every one of them is genuinely safe to delete, you still have to look at the list and press confirm. That's friction.

But consider the alternative. A tool that got it right 199 times out of 200 and silently deleted one file you actually needed would lose your trust permanently — and might have caused real project damage. The friction of review is the premium you pay for a guarantee that the tool does not act without you.

That guarantee is worth more for projects where recovery is hard. And for many of the solo and small-team developers BranchPy is built for, recovery is hard.

Summary

• Errors in destructive operations are much more costly than errors in read operations.
• BranchPy cannot guarantee its classification is complete for every possible Ren'Py project structure.
• Auto-delete requires assumptions that may not hold for your project.
• The staged scan → classify → present → confirm workflow builds in defence-in-depth against false positives.
• The friction of confirmation is intentional — the tool does not act without you.