pharaoh-state-diagram-draft

pharaoh-state-diagram-draft (PLANNED)

Status: DESIGN ONLY. Implementation sentinel FAIL: "pharaoh-state-diagram-draft is planned but not implemented; see SKILL.md".

Shared tailoring rules: see shared/diagram-tailoring.md. Reads [pharaoh.diagrams.state].

Safe-label rules: see shared/diagram-safe-labels.md. Every emitted label / node id / transition label MUST be sanitised per that rule set before the block leaves this skill. sphinx-build does not validate diagram bodies — a parse failure becomes visible only at browser render time. Sanitisation is the first line of defence; the second is pharaoh-diagram-lint run as part of pharaoh-quality-gate.

Purpose

One invocation → one state-machine diagram. Captures discrete states of a component/entity and labeled transitions between them, with optional events, guards, and actions per transition.

Does NOT capture static structure (→ pharaoh-component-diagram-draft, pharaoh-class-diagram-draft). Does NOT capture ordered multi-participant interactions (→ pharaoh-sequence-diagram-draft).

Atomicity

• (a) One state machine in → one diagram out. Nested state machines (composite states) are one machine; two independent machines = two skill invocations.

• (b) Input: {view_title: str, states: list[StateSpec], transitions: list[TransitionSpec], initial_state: str, terminal_states?: list[str], project_root: str, renderer_override?, on_missing_config?, papyrus_workspace?, reporter_id: str} where StateSpec = {id: str, label: str, kind?: "simple"|"composite"|"choice"|"junction", sub_states?: list[StateSpec], entry?: str, exit?: str}, TransitionSpec = {from: str, to: str, event?: str, guard?: str, action?: str}. Output: one RST directive block.

• (c) Reward: fixture — lifecycle draft → in_review → approved → published, plus rejected terminal off in_review. Scorer:

  1. Output starts with renderer-specific directive.
  2. Exactly one initial-state marker ([*] --> Mermaid, [*] --> PlantUML).
  3. initial_state is the target of the initial-state arrow.
  4. Every ID in states appears as a state node.
  5. Every transition renders with correct arrow and label (event [guard] / action).
  6. Every ID in terminal_states has a transition → [*].
  7. With a composite state containing sub_states, the sub-states are nested inside the composite (Mermaid: state Foo { ... }; PlantUML: state Foo { ... }).

  Pass = all 7.

• (d) Reusable: any lifecycle (workflow states, device modes, protocol states, order status machine).

• (e) One machine per call.

Input highlights

• states: all states, possibly nested via sub_states. Composite states declare kind = "composite".
• transitions: from/to reference state IDs, including sub-state IDs (cross-boundary transitions supported).
• initial_state: REQUIRED. Must be an ID in states. There is exactly one initial state; if the machine has multiple "entry points" from outer context, model them via transitions from [*] at the composite level.
• terminal_states (optional): list of IDs that have implicit transition to [*] (final pseudo-state). A machine may have zero terminal states (infinite loop) — valid.

Transition label format

Renderer-independent format: event [guard] / action.

• event optional (unlabeled transition = auto).
• guard in square brackets, optional.
• action after slash, optional.

If all three are absent, render an unlabeled arrow.

Output

Mermaid:

.. mermaid::
   :caption: <view_title>

   stateDiagram-v2
       [*] --> draft
       draft --> in_review : submit
       in_review --> approved : approve [reviewer_count >= 2]
       in_review --> rejected : reject / notify_author
       approved --> published : publish
       rejected --> [*]
       published --> [*]

PlantUML:

.. uml::
   :caption: <view_title>

   @startuml
   [*] --> draft
   draft --> in_review : submit
   in_review --> approved : approve [reviewer_count >= 2]
   in_review --> rejected : reject / notify_author
   approved --> published : publish
   rejected --> [*]
   published --> [*]
   @enduml

Non-goals

• No state-from-code extraction — callers supply states and transitions explicitly. A future pharaoh-states-from-source skill could infer from match statements / switch / FSM libraries, but is a separate concern.
• No timing annotations (real-time deadlines, timer events) — sequence diagrams are a better fit for temporal constraints.
• No concurrency regions by default — a future extension may add orthogonal regions; for now, sub_states are strictly hierarchical.
• No auto-detection of terminal states — caller provides them.

Interaction with tailoring

Some projects (e.g. workflow-heavy ubproject.toml with lifecycle state enums) already declare state machines implicitly — sphinx-needs status enum is a two-line state machine. A caller might want to derive the diagram from the project's workflows.yaml (when present). That derivation is NOT this skill's concern; the caller invokes pharaoh-state-diagram-draft with explicit states and transitions. A wrapper that reads workflows.yaml and calls this skill is orchestration, not atomic.