name	broken-not-unnecessary
description	Before deleting or removing a feature that "rarely works" or "never completes," verify WHY it fails. The failure mode often reveals an implementation bug with a fixable root cause rather than a genuine requirement to remove. Trigger keywords: rarely completes, never fires, dead code, delete step, remove feature, noop, informational screen, collects no data, always fails.

Broken Not Unnecessary

Is the failure intrinsic to the requirement, or is it an implementation constraint?

A plan proposes removing a feature because it "rarely completes," "collects no data," or "never fires." The plan is correct about the symptom but wrong about the cause.

Example: A multi-step wizard has a payment integration step that "rarely completes." Plan said: delete it. Actual reason: the endpoint requires an authenticated session, but the user account doesn't exist yet at that wizard step. Fix: reorder steps so the account is created first. Deleting it would have broken payment processing entirely.

Process

Read the actual handler — understand what it does when it runs correctly
Find the failure path — why does it fail or rarely complete?
If the implementation constraint were removed, would this feature be valuable?
- Yes → restructure so the constraint is satisfied (reorder steps, move the call to a context that has the session/auth/config) — NOT strip the constraint itself; deleting an auth/validation check to make a step "complete" trades a broken feature for a security hole.
- No → delete it, but stage it: disable behind a flag and confirm nothing breaks before hard-deleting.
Confirm the fix worked: re-measure the original completion/failure rate. A reorder that only partially fixes a race leaves the feature broken at a lower rate — don't mark it fixed on the change alone.

Signals: Fix, Not Delete

Feature works in one context (post-login) but not another (pre-login wizard)
Feature requires auth/session/config that doesn't exist at the call site
Deleting it breaks a cross-app integration (payments, SSO, webhooks)

Signals: Delete

Data collected is provably never read or forwarded
Feature only sets a progress flag and discards the payload
No cross-app impact; business requirement has changed

Broken Not Unnecessary

Is the failure intrinsic to the requirement, or is it an implementation constraint?

A plan proposes removing a feature because it "rarely completes," "collects no data," or "never fires." The plan is correct about the symptom but wrong about the cause.

Process

Read the actual handler — understand what it does when it runs correctly

Find the failure path — why does it fail or rarely complete?

If the implementation constraint were removed, would this feature be valuable?

Yes → restructure so the constraint is satisfied (reorder steps, move the call to a context that has the session/auth/config) — NOT strip the constraint itself; deleting an auth/validation check to make a step "complete" trades a broken feature for a security hole.
No → delete it, but stage it: disable behind a flag and confirm nothing breaks before hard-deleting.

Confirm the fix worked: re-measure the original completion/failure rate. A reorder that only partially fixes a race leaves the feature broken at a lower rate — don't mark it fixed on the change alone.

Signals: Fix, Not Delete

Feature works in one context (post-login) but not another (pre-login wizard)

Feature requires auth/session/config that doesn't exist at the call site

Deleting it breaks a cross-app integration (payments, SSO, webhooks)

Signals: Delete

Data collected is provably never read or forwarded

Feature only sets a progress flag and discards the payload

No cross-app impact; business requirement has changed

broken-not-unnecessary