transition

name	transition
description	Define how state changes over time through rules, triggers, and effects. Use when modeling state machines, defining workflows, specifying event handlers, or documenting system dynamics.
argument-hint	[from_state] [to_state] [triggers]
disable-model-invocation	false
user-invocable	true
allowed-tools	Read, Grep
context	fork
agent	explore
layer	MODEL

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

1. Identify state variables: Determine what can change

   • Extract mutable properties from state model
   • Identify discrete vs continuous variables
   • Note invariants (what cannot change)

2. Discover triggers: Find what causes state changes

   • Identify events (user actions, system events)
   • Find conditions (thresholds, timeouts)
   • Note external inputs that affect state

3. Define preconditions: Specify when transitions can occur

   • Document required state for transition
   • Identify guards and conditions
   • Note blocking conditions

4. Specify effects: Document what changes during transition

   • List state variable changes
   • Note side effects (events emitted, actions taken)
   • Capture ordering constraints

5. Validate completeness: Check for missing transitions

   • Identify unreachable states
   • Find states with no outgoing transitions
   • Note non-deterministic cases

6. Ground rules: Document evidence for each transition rule

   • Reference code, configuration, or documentation
   • Note confidence in each rule

Output Contract

Return a structured object:

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:

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

Output:

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:

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

Output:

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