2.3 KiB
Reflection: Resolve destructive semantics before implementing deletion
- Task:
20260813-ended-project-delete-6a714b5b - Date: 2026-08-13
- Status: Confirmed workflow lesson
What happened
The first project-removal implementation treated any queue history as a permanent hard-delete blocker and told the administrator to end the project. That message was internally contradictory: ending the project did not change the blocker, so the user could never complete the requested removal workflow.
The database constraints correctly signaled that operational and audit history must not be casually cascaded, but they did not by themselves define the product meaning of “delete.” The missing decision was whether the user intended destructive purge, operational removal with retained history, or simple status closure.
Why it matters
Deletion labels often conceal several distinct domain actions. Implementing the safest database behavior without first resolving the user-visible lifecycle can create a technically guarded endpoint that has no usable success path. It can also force a later schema and query audit because archival affects every list, authorization path, cache, direct lookup, and background tool—not just the delete handler.
Better workflow
Before implementing a destructive command, establish and test a small lifecycle table: entity state, presence of retained history, requested action, resulting visibility, retained data, and whether restoration or identifier reuse is allowed. Treat ordinary listings and historical attribution as separate query contracts. Then inventory all readers and writers against that contract before editing the endpoint.
Promotion candidate
- Target: repository planning/review guidance for destructive lifecycle changes.
- Proposal: require an explicit delete/archive/purge semantics check and an ordinary-list versus history-query inventory before implementation.
- Evidence: the original guarded hard-delete path could never succeed for the exact ended project it instructed the user to create.
- Future impact: reduces contradictory workflows and prevents archived data from leaking through secondary lists, stale grants, caches, seeds, or direct identifiers.
- Human confirmation: required before promoting this lesson into shared canonical guidance.