02-llm-editing-workflow/07-deletion-policy.md

Deletion policy

Deletion policy

Files in Vroq apps should **not be deleted directly** when working through LLM edits.

Instead, files should be marked as deleted in a way that intentionally breaks builds if the file is still referenced.

Why this policy exists

Directly deleting files can cause hidden problems:

• remaining imports may silently break later
• features may still reference the file indirectly
• debugging becomes harder because the file history disappears

The deletion marker ensures the failure happens immediately and visibly.

Correct deletion procedure

When a file must be removed, replace its contents with the following two lines at the top of the file:

// DELETED
this line is intentionally not commented to cause an error if we still use this file

This guarantees that:

• the file still exists
• any remaining imports produce an obvious error
• the deletion intent is documented

When deletion is appropriate

Deletion markers should be used when:

• a feature file has been replaced by a cleaner implementation
• duplicated helpers have been consolidated
• an old section or component is no longer used
• a refactor removed a previously required file

When not to delete

Do not mark a file as deleted when:

• the file may still be reused
• the change is temporary
• the behavior can be improved instead of removed

Often it is better to refactor or reuse the file than delete it.

Final rule

Deletion should be rare. Prefer improving existing files and consolidating logic instead of removing code unless the removal is clearly justified.