Update to Planning Skills

{
  "description": "Derive states and transitions from an accepted breadboard when retries, timeouts, approvals, lifecycle stages, or multiple valid actions make behavior difficult to review.",
  "included_files": [],
  "name": "statechart",
  "skill_md_contents": "---\nname: statechart\ndescription: Derive states and transitions from an accepted breadboard when retries, timeouts, approvals, lifecycle stages, or multiple valid actions make behavior difficult to review.\nlicense: MIT\n---\n\n# Statechart\n\nUse this skill when an accepted breadboard contains meaningful state complexity and the team needs a more precise behavioral view before implementation.\n\n## Goal\n\nDerive a bounded statechart from selected breadboard rows so humans and agents can see:\n\n- the meaningful states in scope\n- the events that move the system between states\n- the conditions that must be true\n- the effects that occur\n- nested or parallel behavior when it is explicitly supported\n- gaps that the breadboard does not yet specify\n\nThe output is a derived view. The breadboard tables remain the source of truth.\n\n## Use this when\n\nUse a statechart for a selected scope or slice with behavior such as:\n\n- loading, success, failure, retry, or cancellation\n- drafts, review, approval, publication, or archival\n- permissions or role-dependent behavior\n- timers, deadlines, or timeouts\n- background jobs or external messages\n- mutually exclusive modes\n- several valid actions from the same state\n- nested stateful regions that are hard to understand from wiring alone\n\nDo not use this skill for a simple navigation sequence when the breadboard already makes the behavior clear.\n\n## Inputs\n\nUse:\n\n- an accepted breadboard\n- the selected scope, place, chunk, or slice to model\n- relevant constraints and open questions\n- executable-breadboard details when they already exist\n\nDo not derive a statechart from raw notes when no breadboard has been accepted.\n\n## Core rule\n\n```text\nBreadboard tables = source of truth\nState-transition table = derived behavioral interpretation\nMermaid statechart = visual projection\n```\n\nPreserve breadboard IDs. Never silently add behavior to the breadboard.\n\nWhen the statechart requires an event, guard, effect, or state that is missing from the breadboard:\n\n1. mark it as missing or inferred\n2. explain why it matters\n3. recommend a breadboard update\n4. do not present the inference as selected behavior\n\n## Core concepts\n\n### State\n\nA meaningful condition in which the user or system has a distinct set of possible next actions or outcomes.\n\nA state may come from:\n\n- a place\n- a user-visible local state\n- a product-relevant store value\n- a meaningful waiting condition\n- a system lifecycle stage\n\nDo not turn every place, component, or stored field into a state.\n\n### Event\n\nSomething that may cause a transition.\n\nClassify the trigger when useful:\n\n- `user` — a person acts\n- `automatic` — the system proceeds as soon as conditions are met\n- `message` — an external system or asynchronous process responds\n- `time` — a deadline, delay, or timeout occurs\n\n### Guard\n\nA condition that must be true before the transition can occur.\n\nExamples:\n\n- payment details are valid\n- the current user is an approver\n- the request still matches the pending operation\n\n### Effect\n\nThe product-relevant consequence of taking the transition.\n\nExamples:\n\n- request authorization\n- save the draft\n- show the duplicate warning\n- mark the job as failed\n\n### Transition\n\nA change from one state to another caused by an event, optionally constrained by a guard and accompanied by an effect.\n\n### Hierarchy\n\nUse parent states only when they make a complex stateful area easier to collapse and understand.\n\nDo not invent hierarchy from visual proximity alone. Ground it in breadboard places, subplaces, chunks, or an explicitly selected scope.\n\n## Procedure\n\n1. Select one bounded breadboard scope or slice.\n2. Read the relevant Places, UI Affordances, Non-UI Affordances, Stores, `Wires Out`, and `Returns To` rows.\n3. Identify only the states that change what can happen next or what the user can observe.\n4. Assign state IDs such as `ST1`, while preserving the source breadboard IDs.\n5. Derive transitions from explicit wiring and product-relevant branches.\n6. Separate each transition into event, trigger type, guard, effect, and destination state.\n7. Add parent states only where the breadboard supports a meaningful hierarchy.\n8. Add initial, terminal, retry, cancellation, timeout, and failure states only when explicitly specified, or clearly mark them as missing.\n9. Produce the state inventory and transition table before drawing the diagram.\n10. Render an optional Mermaid statechart from the tables.\n11. List missing behavior, unresolved ambiguity, and any proposed breadboard updates.\n\n## Required output\n\n### Scope\n\nName the selected breadboard scope or slice and the source artifact.\n\n### State inventory\n\n| State ID | Source breadboard IDs | State | Parent state | Meaning | Status |\n| --- | --- | --- | --- | --- | --- |\n| ST1 | P2 | Autopay setup | Billing | User is configuring Autopay | explicit |\n\nUse `Status` values:\n\n- `explicit` — directly supported by the breadboard\n- `inferred` — reasonable interpretation that requires confirmation\n- `missing` — needed for a complete model but absent from the breadboard\n\n### Transition table\n\n| Transition ID | From | Trigger type | Event | Guard | Effect | To | Source wiring | Status |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| TR1 | ST1 | user | Submit | Details valid | Request authorization | ST2 | U4 → N4 | explicit |\n\n### Mermaid statechart\n\nUse `stateDiagram-v2` and preserve the state IDs from the inventory.\n\n```mermaid\nstateDiagram-v2\n    ST1: Autopay setup\n    ST2: Authorization pending\n    ST3: Autopay active\n    ST4: Authorization failed\n\n    ST1 --> ST2: Submit [details valid]\n    ST2 --> ST3: Provider approves\n    ST2 --> ST4: Timeout\n```\n\nWhen imported canonical IDs contain hyphens, Mermaid identifiers may replace them with underscores, but labels and tables must retain the canonical IDs.\n\n### Gaps and proposed breadboard updates\n\nFor every unsupported inference, state:\n\n- what is missing\n- why it matters\n- which breadboard rows should be added or changed\n\n## Quality checks\n\nBefore finishing, verify:\n\n- every state maps to one or more breadboard IDs, or is explicitly marked missing\n- every transition has valid source and destination states\n- every transition names an event\n- guards are conditions, not actions\n- effects are consequences, not destination states\n- important product-visible branches are represented\n- asynchronous waits distinguish messages from timeouts when the breadboard specifies them\n- retry, cancellation, and failure behavior are not invented\n- hierarchy reflects explicit scope, subplaces, or chunks\n- the Mermaid diagram matches the state and transition tables\n- no statechart output overrides or silently edits the breadboard\n\n## Do not\n\nDo not:\n\n- make statecharts mandatory for every breadboard\n- replace the breadboard with the statechart\n- create implementation code, SCXML, framework configuration, or production schemas unless explicitly requested\n- convert every UI screen into a state without checking whether behavior actually changes\n- add parallel states merely because two operations could theoretically happen at once\n- hide missing behavior by guessing\n\n## Recommended output structure\n\n```md\n# [Project / scope] — Statechart\n\n## Source\n- Breadboard:\n- Scope or slice:\n\n## State inventory\n[table]\n\n## Transition table\n[table]\n\n## Mermaid statechart\n[diagram]\n\n## Gaps and proposed breadboard updates\n- ...\n```\n"
}