Intent

Define the rules governing how a system's state changes over time. This capability captures state machine semantics: what triggers transitions, what preconditions must hold, and what effects occur.

Success criteria:

•Transition rules clearly specified
•Preconditions and effects documented
•Triggers identified with evidence
•State machine is deterministic (or non-determinism noted)

Compatible schemas:

•schemas/output_schema.yaml

Inputs

Parameter	Required	Type	Description
`from_state`	Yes	object	Initial state or state pattern
`to_state`	No	object	Target state (optional for discovery mode)
`triggers`	No	array	Events or conditions that cause transition
`scope`	No	string	Domain to analyze for transitions

Procedure

•
Identify state variables: Determine what can change
- •Extract mutable properties from state model
- •Identify discrete vs continuous variables
- •Note invariants (what cannot change)
•
Discover triggers: Find what causes state changes
- •Identify events (user actions, system events)
- •Find conditions (thresholds, timeouts)
- •Note external inputs that affect state
•
Define preconditions: Specify when transitions can occur
- •Document required state for transition
- •Identify guards and conditions
- •Note blocking conditions
•
Specify effects: Document what changes during transition
- •List state variable changes
- •Note side effects (events emitted, actions taken)
- •Capture ordering constraints
•
Validate completeness: Check for missing transitions
- •Identify unreachable states
- •Find states with no outgoing transitions
- •Note non-deterministic cases
•
Ground rules: Document evidence for each transition rule
- •Reference code, configuration, or documentation
- •Note confidence in each rule

Output Contract

Return a structured object:

yaml

rules:
  - id: string  # Unique rule identifier
    name: string  # Human-readable name
    from: object  # Source state pattern
    to: object  # Target state pattern
    trigger:
      type: string  # event, condition, timeout
      specification: any  # Trigger details
    preconditions: array[string]  # Required conditions
    effects: array[string]  # State changes
    priority: number  # Resolution priority for conflicts
analysis:
  reachability: object  # Which states are reachable
  completeness: number  # Coverage estimate
  non_determinism: array  # Ambiguous transitions
confidence: 0..1
evidence_anchors: ["file:line", "doc:section"]
assumptions: []

Field Definitions

Field	Type	Description
`rules`	array	Transition rules
`rules[].from`	object	Source state pattern
`rules[].to`	object	Target state pattern
`rules[].trigger`	object	What causes the transition
`rules[].preconditions`	array	Conditions that must hold
`rules[].effects`	array	Changes caused by transition
`analysis`	object	State machine analysis results

Examples

Example 1: Order State Transitions

Input:

yaml

from_state:
  entity: "order"
  status: "*"
scope: "order lifecycle"

Output:

yaml

rules:
  - id: "order-create"
    name: "Create Order"
    from: { status: null }
    to: { status: "pending" }
    trigger:
      type: "event"
      specification: "OrderCreated"
    preconditions:
      - "cart is not empty"
      - "user is authenticated"
    effects:
      - "order.status = 'pending'"
      - "order.created_at = now()"
      - "emit OrderCreatedEvent"
    priority: 1
  - id: "order-confirm"
    name: "Confirm Order"
    from: { status: "pending" }
    to: { status: "confirmed" }
    trigger:
      type: "event"
      specification: "PaymentReceived"
    preconditions:
      - "payment.amount >= order.total"
      - "inventory available"
    effects:
      - "order.status = 'confirmed'"
      - "order.confirmed_at = now()"
      - "reserve inventory"
      - "emit OrderConfirmedEvent"
    priority: 1
  - id: "order-cancel"
    name: "Cancel Order"
    from: { status: ["pending", "confirmed"] }
    to: { status: "cancelled" }
    trigger:
      type: "event"
      specification: "CancelRequested"
    preconditions:
      - "order.status != 'shipped'"
    effects:
      - "order.status = 'cancelled'"
      - "release inventory"
      - "emit OrderCancelledEvent"
    priority: 2
analysis:
  reachability:
    pending: ["confirmed", "cancelled"]
    confirmed: ["shipped", "cancelled"]
    shipped: ["delivered"]
    delivered: []
    cancelled: []
  completeness: 0.9
  non_determinism: []
confidence: 0.85
evidence_anchors:
  - "app/models/order.rb:45-120"
  - "app/services/order_service.rb:15-80"
assumptions:
  - "State machine defined in Order model"
  - "All transitions go through OrderService"

Example 2: Authentication State Transitions

Input:

yaml

from_state:
  entity: "user_session"
  status: "unauthenticated"
scope: "authentication flow"

Output:

yaml

rules:
  - id: "login-success"
    name: "Successful Login"
    from: { authenticated: false }
    to: { authenticated: true }
    trigger:
      type: "event"
      specification: "CredentialsValidated"
    preconditions:
      - "credentials.valid == true"
      - "user.locked == false"
      - "failed_attempts < max_attempts"
    effects:
      - "session.authenticated = true"
      - "session.user_id = user.id"
      - "session.expires_at = now() + 24h"
      - "reset failed_attempts"
    priority: 1
  - id: "login-failure"
    name: "Failed Login Attempt"
    from: { authenticated: false }
    to: { authenticated: false, failed_attempts: "+1" }
    trigger:
      type: "event"
      specification: "CredentialsRejected"
    preconditions: []
    effects:
      - "increment failed_attempts"
      - "if failed_attempts >= max_attempts: lock user"
    priority: 1
  - id: "logout"
    name: "Logout"
    from: { authenticated: true }
    to: { authenticated: false }
    trigger:
      type: "event"
      specification: "LogoutRequested"
    preconditions: []
    effects:
      - "session.authenticated = false"
      - "session.destroy()"
    priority: 1
analysis:
  reachability:
    unauthenticated: ["authenticated", "locked"]
    authenticated: ["unauthenticated"]
    locked: ["unauthenticated"]
  completeness: 0.95
  non_determinism: []
confidence: 0.9
evidence_anchors:
  - "app/controllers/sessions_controller.rb:10-50"
  - "app/models/user.rb:80-95"
assumptions:
  - "Session timeout handled by middleware"
  - "Lock mechanism implemented in User model"

Verification

• Each rule has from and to state patterns
• Triggers are specified for each rule
• Preconditions are testable
• Effects are specific and verifiable
• Reachability analysis covers all known states

Verification tools: Read (to verify code references)

Safety Constraints

•mutation: false
•requires_checkpoint: false
•requires_approval: false
•risk: low

Capability-specific rules:

•Document non-determinism explicitly
•Flag missing transitions for terminal states
•Note when transitions have side effects
•Do not execute transitions while modeling

Composition Patterns

Commonly follows:

•state - State model provides basis for transitions
•observe - Observations reveal transition patterns
•discover - Discovery finds unknown transitions

Commonly precedes:

•simulate - Transitions drive simulation
•plan - Transitions inform action planning
•verify - Transitions specify expected behavior

Anti-patterns:

•Never use transition to execute changes (use mutate)
•Avoid modeling transitions without state model first

Workflow references:

•See reference/workflow_catalog.yaml#world_model_build for transitions in world modeling
•See reference/workflow_catalog.yaml#digital_twin_sync_loop for transition application