reentry-pass

name

reentry-pass

description

Apply the five re-entry questions to an in-scope active state of a software system to specify how it behaves when entered from contexts other than the canonical one (after time has passed, from a notification or deep link, without preceding state, after underlying data has changed, or during/after a system failure). Use whenever a user has triaged states and is specifying behaviour for systems where re-entry matters: notifications, deep links, multi-device flows, out-of-band messages, push reminders, scheduled tasks the user returns to. Use also after a state audit on an existing product to specify gap states that are in-scope and active. The fourth step in the Stateful method. Do not use on `out` states or transient states that users do not meaningfully remain on (validation, commit). Do not collapse the five questions into a single "returning user" variant; that is the failure mode this skill exists to prevent.

Re-Entry Pass

Takes an in-scope active state and produces its re-entry specification by applying the five re-entry questions.

Output discipline

No preamble, no narration of the procedure, no restating the state or the questions. Deliver the output format below plus only what needs the user's decision. Terse but complete: specifications stay 2 to 4 sentences per applicable question; not-applicable verdicts get their one-line reason and nothing more.

Procedure

Before starting. Read STATEFUL.md from the working directory if it exists. Use the system sentence and triage context from it to interpret the state being passed. If no system sentence is present, ask the user for one.

1. Read the state's canonical rendering and the scope note from triage.
2. For each of the five questions, decide whether it applies to this state. Mark not-applicable explicitly; do not silently skip.
   • Q1: What does the user see if they return to this state after time has passed?
   • Q2: What does the user see if they arrive from a notification, deep link, or different device?
   • Q3: What does the user see if they arrive without the preceding state having been shown?
   • Q4: What does the user see if the underlying data has changed since they last saw this state?
   • Q5: What does the user see if they arrive during or after a failure in the system?
3. For each applicable question, write a specification of 2–4 sentences. Describe the rendering under that re-entry condition and the system behaviour required.
4. Flag any specification that conflicts with the canonical rendering. These are design decisions, not errors; the user must choose.
5. If state-map.json exists in the working directory (the user opted in during the state-list step), update the relevant state's reentry_variants array with the new specifications. Leave the file untouched if it does not exist.
6. Return the state's re-entry specification, one paragraph per applicable question.

Working memory. Update STATEFUL.md in the working directory: append to the ## Re-entry specs section a line for the state just passed (state id + count of applicable variants). Full per-question specifications belong in the design file or a separate notes file, not in this summary. If STATEFUL.md does not exist, create it. Stamp Last updated: <date> by reentry-pass.

Inputs required

• The state's name, category, and canonical rendering description.
• The system sentence (context for what "re-entry" means for this system).
• Optional: known constraints from triage (particularly which adjacent states are out and how that constrains the specification).

Output format

## State: <name>

**Canonical rendering.** <one-paragraph summary>

**Q1. Return after time has passed.** <specification, or "not applicable: reason">
**Q2. Arrival from notification, deep link, or different device.** <specification, or "not applicable: reason">
**Q3. Arrival without the preceding state.** <specification, or "not applicable: reason">
**Q4. Underlying data has changed.** <specification, or "not applicable: reason">
**Q5. Arrival during or after a failure.** <specification, or "not applicable: reason">

Common failure modes

• Treating re-entry as a single variant. A "returning user" specification is not a re-entry pass. Each question is distinct.
• Treating re-entry as copy work. Re-entry specifications affect data-model, session-scoping, and state-validation logic, not only language.
• Omitting Q4 and Q5. Q4 (data changed) and Q5 (prior failure) are the two most commonly skipped, and the two that produce the most production incidents.
• Designing re-entry on top of the canonical state. Re-entry conditions may contradict the canonical rendering. The specification is its own artefact, not a variant stylesheet.
• Specifying without checking the token or data model. Re-entry specifications that assume consistent state on arrival repeat the failure they are meant to address.

Example

Input: State 8 from the password-reset state list: "New-password form, empty".

Output (abbreviated, see full version in the worked example):

## State: New-password form, empty

**Canonical rendering.** A form with password and confirm-password fields, policy hints, and a submit button. Account context (which account is being reset) is displayed.

**Q1. Return after time has passed.** The token has a validity window. If the user opens the form, leaves, and returns after the window has elapsed, submitting the form must not silently fail. The surface must detect token expiry on focus, not only on submit, and present the appropriate failure state with a path to re-request.

**Q2. Arrival from notification, deep link, or different device.** Canonical arrival. The link may arrive on a device that has never signed in to the account. The surface must not assume any session context; account identity must be derived from the token and shown explicitly.

**Q3. Arrival without the preceding state.** Validate the token presence and correctness before rendering the form. A forwarded link or a malformed URL must not present a submittable form.

**Q4. Underlying data has changed.** Between click and submit, the account's email may have changed, the account may have been deleted, or the user may have reset through another path. Submit must revalidate the token and account state, not only the password value.

**Q5. Arrival during or after a failure.** If the user arrives after a prior submit failed mid-commit, re-check the credential state before offering a second submit.

See EXAMPLES/password-reset/03-reentry-pass.md for the complete worked example.