Specification and Re-entry Pass
Turn triaged conditions into testable contracts. Re-entry is one part of specification, not the only requirement.
Procedure
- Read the confirmed condition map and
STATEFUL.md. Refuse to infer confirmation from agent-written recommendations. - For every
scope: incondition, write:- behavior;
- accountable owner;
- at least one testable acceptance criterion;
- design, implementation, and test links when available.
- Add the category contract:
- Lifecycle state: canonical rendering or observable behavior, allowed/prohibited actions, data and invariants, transitions and guards, stale-data and concurrency behavior.
- Failure: user-facing response and redaction, preserved work, safe retry/alternate path/exit, idempotency, and observability.
- Interruption: persistence window, revalidation, reconciliation, resume/restart destination, and recovery when prior context no longer exists.
- Surface: content priority, supported actions and fallback, freshness, accessibility, authentication, privacy, and redaction.
- For each non-transient in-scope lifecycle state, answer all five re-entry questions:
after_time;alternate_entryfrom notification, deep link, or different device;without_predecessor;data_changed;after_failure.
- Record every answer as:
applicablewith a concrete specification; ornot-applicablewith a reason. Silence is not a verdict.
- Identify high-risk combinations across lifecycle state, interruption, surface, changed data, and dependency condition. Write a scenario and acceptance criterion for each selected combination. Do not enumerate the full Cartesian product.
- Flag conflicts with canonical behavior, adjacent conditions, policies, or implementation constraints for human decision.
- Set
status: specifiedonly when the common contract, category contract, and required re-entry review pass. - Update
STATEFUL.mdwith specified/in-scope totals and re-entry-reviewed/eligible totals. If a JSON mirror exists, update it and runscripts/validate_state_map.py --profile handoff state-map.jsonwhen the full in-scope pass is complete.
Output
## <condition id>: <name>
Category: <state | failure | interruption | surface>
Owner: <role or person>
Behavior:
<observable contract>
Category requirements:
- <requirement>
Acceptance criteria:
- <testable criterion>
Re-entry review (lifecycle states only):
- After time: <applicable specification | not-applicable reason>
- Alternate entry: <...>
- Without predecessor: <...>
- Data changed: <...>
- After failure: <...>
Composite scenarios:
- <high-risk combination and expected behavior>
Failure modes
- Specifying only lifecycle states while leaving in-scope failures, interruptions, and surfaces named but undesigned.
- Restating the description as acceptance criteria.
- Omitting recovery for failures or interruptions.
- Omitting owner or testability.
- Collapsing five re-entry questions into “returning user.”
- Treating re-entry questions as independent when their conditions compose.
- Marking a record specified while required fields remain undecided.