Transition

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

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

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