Teardown: 2FA setup as a state machine
A teardown guide to write the 2FA setup PRD as a state machine with a one‑page state map, a 3×9 acceptance matrix, and clear rollback paths.

For PMs who write PRDs, specs, or one‑pagers for security or any multi‑step flow. By the end you will have a one‑page PRD for 2‑factor enabling: a state map, a 3×9 acceptance matrix, and a clear rollback line for risky moves.
- The problem: screen lists miss state collisions and create edge‑case outages.
- Key idea: write the PRD as a state machine of account + device + auth states.
- Acceptance criteria: matrix of state × action → outcome, UX, error, telemetry.
- Ship it safe: prioritise failure modes, set safe defaults, and define recovery.
Screens are outcomes of states. The spec is the states and their transitions.
Why screen‑first PRDs fail
A list of screens hides the real system. Accounts can have backup codes already. Devices get lost. Verification can be half‑done. Policies can enforce 2FA. If you spec a happy path of screens, you collide with these states and ship outages that support then has to carry.

Steps: write the PRD as a state machine
Define scope and actors
State = account + device + auth factor. Name each actor and who can act.
Enumerate states
List every state the system can be in, not just happy path. Include policy and failure states.
One‑page state map
Make a single header map of nodes and allowed transitions. This is the canonical spec.
Define actions
List actions that can be invoked in any state (e.g., enable, disable, recover).
Matrix acceptance criteria
For each state × action, define expected outcome, UX, error code, telemetry/event.
Node test checklist
Add a short checklist for each node so QA and support can probe it fast.
Prioritise failure modes
Rank by customer impact and rollback cost. Choose safe defaults and clear exits.
Rollback per risky move
Write one explicit rollback line per risky transition. Include trigger and steps.
Review and freeze
Review with security, support, and data. Freeze the header. Then do wires.
Screen list vs state machine
| Aspect | Screen list | State machine |
|---|---|---|
| Edge cases | Hidden or deferred | Enumerated and testable |
| Policy collisions | Found late | Handled in allowed transitions |
| Acceptance criteria | Per screen | Per state × action |
| Telemetry | Page views | State transitions and outcomes |
| Rollback | Ad‑hoc | Planned per risky move |

Worked example: 2FA enabling as a one‑page PRD
Scope: end‑user account 2FA enabling and related recovery. Actions covered: enable, disable, recover. States listed below. Acceptance criteria follow as a matrix. Recovery UX is specified, not left as TODO.
State‑map header
No 2FA
- Entry: new or 2FA removed
- Exit: Enable → S6 (pending) or policy → S7
- Node tests: entry/exit signals; blocked ops clear; event names set
SMS enabled
- Entry: SMS verified
- Exit: Disable → S1; Recover → S8
- Node tests: code delivery; rate‑limit; lockout rules
TOTP enabled
- Entry: app code verified
- Exit: Disable → S1; Recover → S8
- Node tests: time skew; code reuse; lockout rules
Backup codes
- Entry: codes generated
- Exit: Rotate/regen; Disable if only factor → S1
- Node tests: one‑time use; storage; reveal limits
Lost device
- Entry: user flags loss
- Exit: Recover → S8; Resolve → prior state
- Node tests: block risky ops; notify; audit
Pending verification
- Entry: start enable
- Exit: Verify → S2/S3/S4; Cancel → S1
- Node tests: resume flow; expiry; retries
Org‑enforced
- Entry: policy applies
- Exit: Policy change → prior eligible
- Node tests: block disable; admin path; audit
Recovery in progress
- Entry: start recovery
- Exit: Prove → S2/S3/S4; Fail → S5 or hold
- Node tests: step‑up auth; proofing; audit
Suspended
- Entry: risk or abuse
- Exit: Admin unsuspends
- Node tests: no changes; appeal path clear
- Enable 2FA
- Disable 2FA
- Recover access
Acceptance matrix: state × action
| Action | State | Expected outcome | UX | Error code | Telemetry/event |
|---|---|---|---|---|---|
| Enable | S1 No 2FA | Move to S6 (pending) | Prompt to choose factor; show safe defaults | — | 2fa_enable_started |
| Enable | S2 SMS enabled | No state change | Show manage factors; confirm already enabled | ERR_ALREADY_ENABLED | 2fa_enable_noop_already |
| Enable | S3 TOTP enabled | No state change | Show manage factors; confirm already enabled | ERR_ALREADY_ENABLED | 2fa_enable_noop_already |
| Enable | S4 Backup codes | Move to S6 to add a primary factor | Prompt to set SMS/TOTP; keep codes | — | 2fa_add_factor_started |
| Enable | S5 Lost device | Blocked; route to S8 | Explain loss; start recovery | ERR_DEVICE_LOST | 2fa_enable_blocked_lost |
| Enable | S6 Pending verification | No state change | Resume verification; show remaining step | — | 2fa_enable_resume |
| Enable | S7 Org‑enforced | No state change | Direct to enforced setup flow; explain policy | ERR_POLICY_ENFORCED | 2fa_enable_policy_redirect |
| Enable | S8 Recovery in progress | No state change | Continue recovery; defer enable | ERR_RECOVERY_ONGOING | 2fa_enable_blocked_recovery |
| Enable | S9 Suspended | Blocked | Explain suspension; no change | ERR_ACCOUNT_SUSPENDED | 2fa_enable_blocked_suspended |
| Disable | S1 No 2FA | No state change | Confirm already off | ERR_ALREADY_DISABLED | 2fa_disable_noop |
| Disable | S2 SMS enabled | Move to S1 (if allowed) | Require re‑auth; confirm risk; disable | — | 2fa_disable_success |
| Disable | S3 TOTP enabled | Move to S1 (if allowed) | Require re‑auth; confirm risk; disable | — | 2fa_disable_success |
| Disable | S4 Backup codes | If only factor, move to S1; else keep others | Explain impact; allow code revocation | — | 2fa_codes_revoked |
| Disable | S5 Lost device | Blocked; route to S8 | Explain risk; start recovery | ERR_DEVICE_LOST | 2fa_disable_blocked_lost |
| Disable | S6 Pending verification | Cancel enable; move to S1 | Confirm cancel; clear pending | — | 2fa_enable_canceled |
| Disable | S7 Org‑enforced | Blocked | Explain policy; direct to admin | ERR_POLICY_ENFORCED | 2fa_disable_blocked_policy |
| Disable | S8 Recovery in progress | Blocked | Complete recovery first | ERR_RECOVERY_ONGOING | 2fa_disable_blocked_recovery |
| Disable | S9 Suspended | Blocked | Explain suspension; no change | ERR_ACCOUNT_SUSPENDED | 2fa_disable_blocked_suspended |
| Recover | S1 No 2FA | No state change | Explain 2FA not set; suggest enable | ERR_NO_2FA | 2fa_recover_noop |
| Recover | S2 SMS enabled | Move to S8 | Start recovery; identity proof or backup code | — | 2fa_recover_started |
| Recover | S3 TOTP enabled | Move to S8 | Start recovery; identity proof or backup code | — | 2fa_recover_started |
| Recover | S4 Backup codes | No state change if codes used; rotate codes option | Enter code; regain access; offer code rotation | — | 2fa_recover_with_code |
| Recover | S5 Lost device | Move to S8 | Start recovery; guide next steps | — | 2fa_recover_started |
| Recover | S6 Pending verification | No state change | Resume verification or cancel to S1 | — | 2fa_recover_resume_pending |
| Recover | S7 Org‑enforced | No state change | Route to org recovery path | ERR_POLICY_ENFORCED | 2fa_recover_policy_redirect |
| Recover | S8 Recovery in progress | No state change | Continue recovery; show remaining step | — | 2fa_recover_resume |
| Recover | S9 Suspended | Blocked | Explain suspension; support path only | ERR_ACCOUNT_SUSPENDED | 2fa_recover_blocked_suspended |
Rollback plan: risky transitions
| Risky transition | Trigger | Rollback steps | Owner | Telemetry to watch |
|---|---|---|---|---|
| Disable from S2/S3 to S1 | Error spike or lockout complaints | Reinstate prior factor; notify user; log audit; re‑prompt to confirm | On‑call + Support | 2fa_disable_success, lockout_tickets_rate |
| Switch mid S6 (method change) | Verification timeout or drop‑off spike | Revert S6 session to last good step; keep secrets invalid; message resume link | On‑call | 2fa_enable_started, 2fa_enable_canceled |
| Recovery S8 fails into S5 | Proofing fail rate > baseline | Hold in S5; disable risky actions; open support channel; preserve audit | Security + Support | 2fa_recover_started, 2fa_recover_fail |

Ship‑ready checklist
- Every state has clear entry and exit signals.
- Every action in every state has an outcome, UX, error, and event.
- Recovery paths are defined and testable, not TODOs.
- Org policy and suspension are handled without side effects.
- Rollback lines exist for risky moves and name owners.
- Events are bound to dashboards and alerts.
If you want a place to hold this one‑pager and keep the matrix crisp, start it in a PRD. Keep the state map as the header. Then let screens follow the states, not the other way around. You can draft it in the PikoPM PRD.


