| name | state-triage |
| description | Take a state list of software-system states and recommend a scope tag for each (`in` for designed this iteration, `out-with-implication` for deferred but constrains in-scope work, or `out` for deferred with no current implication), with implication notes on the middle category — for the human to confirm. Use whenever a user has a flat list of states from the state-list skill or a state audit and needs to make scope decisions before any design or remediation work begins; whenever someone needs to decide which states to design now versus later without losing the deferred ones; or as the third step in the Stateful method, after the state list in new projects and after audit in existing-project work. Do not use before the state list or audit is complete; partial lists produce partial triage and the missing states get silently dropped. |
State Triage
Takes a state list and produces scope categorisations for each state: in, out-with-implication, or out.
Output discipline
No preamble, no narration of the procedure, no restating the state list. Deliver the output format below plus only what needs the user's decision. Terse but complete: one-line rationale per recommendation; implication notes stay one sentence.
Who decides
Triage is the human's step — the third step of the method, and the one place automation must hand back. When a person runs this skill, they make the calls. When an agent runs it, the agent recommends a scope for each state, with a one-line rationale, then stops and hands the decision to the human — it does not finalise scope itself, and it does not proceed to the re-entry pass or any build work until the human has triaged. Persist scope tags (to state-map.json or STATEFUL.md) only after the human has confirmed or adjusted the recommendation. The agent's job is to make the decision cheap and well-reasoned, not to make it.
Procedure
Before starting. Read STATEFUL.md from the working directory if it exists. Use the ## State list from it as the input list. If no state list is present, ask the user for one (or run the state-list skill first).
- Read the state list in full before making any decisions. Holistic context is required; item-by-item triage without context produces inconsistent scoping.
- For each state, recommend one of three tags (the human confirms — see Who decides):
- in. Will be designed in this iteration.
- out-with-implication. Not designed now, but has design consequences for in-scope work.
- out. Not designed, no current implication; documented so it is not rediscovered later.
- For each out-with-implication state, write a one-sentence note describing the specific implication for in-scope work (what copy, naming, data-model, or constraint it affects).
- For each out state, write a one-sentence note describing why it is out and what would cause it to become in (e.g., "in when SSO is introduced").
- Check consistency: a state tagged in whose preconditions are tagged out is an inconsistency. Resolve.
- (Optional) If layers were assigned in the state list (or if the project is cross-functional), include them in the output table as a Layers column. Add a layer-summary line under totals:
Frontend: <n> · Backend: <n> · Data-model: <n> · Infrastructure: <n> for in-scope states only.
6a. (Optional, failure section) If causes were assigned in the state list, include them in the failure table as a Cause column. Add a cause-summary line under totals: User-input: <n> · System: <n> · External: <n> · Policy: <n> across in-scope failure states. The cause distribution is a useful signal: a list heavy in policy indicates the system enforces many rules and the design must explain them; heavy in external indicates the design must surface dependency status; heavy in user-input indicates the design must coach.
- Present the recommended triage and, when an agent is running this skill, stop for the human to confirm or adjust before anything is persisted (see Who decides).
- If
state-map.json exists in the working directory (the user opted in during the state-list step), update it with the confirmed scope tags. Leave the file untouched if it does not exist; do not re-ask the user.
- Return the annotated list with totals per tag (and layer summary if layers were used).
Working memory. Update STATEFUL.md in the working directory: replace the contents of the ## Triage section with totals (In, Out-with-implication, Out) and one-line implication notes for the middle category. If the file does not exist, create it. Stamp Last updated: <date> by state-triage. If STATEFUL.md contains a ## Graph section, regenerate it with the confirmed scope tags (scope drives the graph's styling) following the state-graph skill's conventions, preserving the cut recorded in ## Decisions.
Inputs required
- The state list (all four categories).
- The scope of the current iteration: what product surfaces, platforms, and conditions are in play.
- Optional: constraints on the iteration (time, team size, known deadlines) that inform where to draw the scope boundary.
Output format
## <category>
| # | State | Scope | Layers (optional) | Cause (failure only, optional) | Note |
|---|---|---|---|---|---|
| 1 | <state> | in | fe, be | | |
| 2 | <state> | out-with-implication | fe | | <one-sentence implication> |
| 3 | <failure state> | in | fe, be | policy | |
## Totals
- In: <n>
- Out-with-implication: <n>
- Out: <n>
(Optional) By layer (in-scope only):
- Frontend: <n>
- Backend: <n>
- Data-model: <n>
- Infrastructure: <n>
(Optional) Failure causes (in-scope failures only):
- User-input: <n>
- System: <n>
- External: <n>
- Policy: <n>
Common failure modes
- Finalising scope autonomously. When an agent runs triage, it recommends and the human decides. An agent that assigns and persists scope without confirmation has usurped the step; scope must be the human's call, even when a tool drafts it.
- Treating
out as deletion. out is documentation, not removal. The state remains in the map; the design work does not happen this iteration.
- Omitting the implication note. An
out-with-implication state without a note is indistinguishable from an out state, and the implication gets lost.
- Scoping everything
in. Deferring triage by refusing to decide produces a plan that cannot be executed.
- Scoping
out states the team has committed to. Triage contradicting commitments elsewhere creates misalignment; check with stakeholders.
- Scope based on difficulty rather than relevance. A hard state is not an
out state; it is a hard in state.
Example
Input: A state list for password reset (see the state-list skill example).
Partial output (failure category only):
## Failure states
| # | State | Scope | Note |
|----|--------------------------------|----------------------|-------------------------------------------------------------------------------------|
| 15 | Email not recognised | in | |
| 18 | Email deliverability failure | out-with-implication | Acknowledgement copy must set an expectation compatible with silent failure. |
| 19 | Email delayed | out-with-implication | Acknowledgement surface must offer a re-request affordance after a cooldown. |
| 26 | Account is SSO-only | out | Product does not currently support SSO. Becomes in-scope when SSO is introduced. |
| 27 | New password fails policy | in | |
See EXAMPLES/password-reset/02-triage.md for the complete worked example.
