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:

```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