needsReview Is a Feature

"The bravest thing a file manager can do is stop and admit 'I'm not sure.' Every tool that lost your data was too confident to say it."

The State Most Tools Refuse to Have

Most software treats 'stuck, uncertain' as a failure to paper over — retry silently, pick a default, push through so the user isn't bothered. Waygate does the opposite: it has a first-class state called needsReview whose entire purpose is to stop and hold when the evidence for a destructive step runs out. Entering needsReview isn't the operation failing; it's the operation succeeding at the one thing that matters most — not guessing with your files.

What Lands in needsReview

The rule is specific: after uncertainty, Waygate will not auto-retry a move, a replace, a Trash, or a cleanup. If an interrupted operation reaches a destructive barrier and the journal can't deterministically prove the safe next step, it stops in needsReview and waits for a human. A crash between publishing a destination and deleting the source; a replace whose backup state is ambiguous; a cleanup that can't prove an artifact is truly orphaned — all of these hold rather than proceed.

Why Stopping Beats Retrying

Auto-retry feels helpful and is quietly lethal for destructive operations. Retrying a delete you weren't sure about doesn't become safer the second time; it just runs the risky step again with the same missing evidence. A stop, by contrast, costs the user a moment of attention and loses nothing. needsReview trades a small, visible interruption for the elimination of an entire class of silent data loss. That trade is always worth it when the downside is a file that can't come back.

needsReview is a deliberate first-class state: after uncertainty, Waygate never auto-retries a move, replace, Trash, or cleanup. An interrupted destructive barrier without deterministic evidence stops and waits for a human. Stopping costs a moment of attention; guessing can cost a file — so the stop is the feature, not the failure.

Auto-retry is where the data goes. The single most common way 'robust' file tools lose data is a well-meaning retry loop around a destructive operation: the first attempt left an ambiguous state, and the retry — run with the same incomplete information — resolves the ambiguity the wrong way. A destructive step that failed once should not be re-run automatically; it should be reviewed. needsReview is the discipline of never letting confidence outrun evidence.

Code

needsReview holds; it never auto-retries destruction·swift

func handleInterrupted(_ op: OperationHandle, _ evidence: Evidence) {
    let isDestructive = op.kind.isDestructive   // move, replace, trash, cleanup
    if isDestructive && !evidence.provesSafeNextStep {
        // Do NOT loop-retry. Do NOT pick a default. HOLD:
        journal.mark(op, .needsReview,
                     summary: evidence.humanReadableAmbiguity)
        ui.presentReviewQueue(op)   // a human sees exactly what's uncertain
        return
    }
    // Only non-destructive or deterministically-safe steps proceed:
    Task { try? await engine.resume(op, from: evidence) }
}
// The temptation this refuses: `for attempt in 1...3 { try? retry(op) }`
// around a delete. Three tries with the same missing evidence is three
// chances to lose the file, not a fix.

Exercise

Find a place in software where a retry loop wraps a risky operation (a payment, a delete, an email send, a file move). Ask: does retrying with the same inputs actually make it safer, or does it just re-run the risk? Then design the needsReview alternative: what would the tool show a human instead of retrying, and what small decision would it ask for?

Hint

Retrying is genuinely safe only for idempotent, non-destructive operations — reading, or a write that's safe to repeat. For destructive or side-effectful steps (charge a card, delete a file, send a message), a blind retry just risks doing the harmful thing twice or resolving an ambiguity wrongly. The needsReview alternative surfaces the ambiguous state and its evidence and asks the human one concrete question, replacing a dangerous automatic guess with a cheap, safe decision.

The State Most Tools Refuse to Have

What Lands in needsReview

Why Stopping Beats Retrying

Code

External links

Exercise

Progress

Comments 0