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/transition_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 workflow_catalog.yaml#world_model_build for transitions in world modeling
- See workflow_catalog.yaml#digital_twin_sync_loop for transition application