simulate

name: simulate
description: Run what-if scenarios to explore outcomes and test hypotheses. Use when evaluating alternatives, stress-testing designs, exploring edge cases, or predicting system behavior under different conditions.
argument-hint: "[scenario] [initial_state] [steps]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Bash
context: fork
agent: explore
layer: MODEL

Intent

Execute mental simulations of scenarios to explore outcomes without making real changes. This capability enables safe exploration of "what-if" questions and helps identify risks before action.

Success criteria:
- Scenario executed through logical steps
- Multiple outcomes considered
- Key decision points identified
- Assumptions made explicit

Compatible schemas:
- schemas/simulation_output.yaml

Inputs

Procedure

1) Set up scenario: Define what is being simulated
- Clarify the intervention or change being tested
- Establish initial conditions
- Define simulation boundaries

2) Initialize state: Establish starting point
- Use provided initial_state or current system state
- Validate state is consistent
- Note any simplifications

3) Execute simulation: Step through scenario
- Apply changes specified in scenario
- Propagate effects through state
- Track state at each step

4) Explore branches: Consider alternative paths
- Identify decision points
- Explore likely alternative outcomes
- Note probability of each branch

5) Evaluate outcomes: Assess simulation results
- Compare final states across branches
- Identify risks and opportunities
- Note unexpected behaviors

6) Document simulation: Record process and results
- List assumptions made
- Note limitations of simulation
- Provide evidence for conclusions

Output Contract

Return a structured object:

outcomes:
  - branch_id: string  # Unique branch identifier
    probability: number  # Estimated likelihood
    final_state: object  # State after simulation
    key_events: array[string]  # Notable events during simulation
    risks: array[string]  # Identified risks
trajectory:
  - step: number
    state: object  # State at this step
    changes: array[string]  # What changed
final_state: object  # Most likely final state
insights:
  - type: string  # risk, opportunity, surprise
    description: string
    severity: string  # low, medium, high
simulation_meta:
  steps_executed: number
  branches_explored: number
  assumptions: array[string]
confidence: 0..1
evidence_anchors: ["model:component", "assumption:id"]

Field Definitions

Examples

Example 1: Simulate Dependency Upgrade

Input:

scenario:
  type: "dependency_upgrade"
  change: "Upgrade Rails from 6.1 to 7.0"
initial_state:
  rails_version: "6.1.7"
  ruby_version: "3.1.0"
  gems_count: 85
steps: 5

Output:

outcomes:
  - branch_id: "success_path"
    probability: 0.60
    final_state:
      rails_version: "7.0.8"
      breaking_changes_resolved: true
      tests_passing: true
    key_events:
      - "ActiveStorage API changes detected"
      - "Zeitwerk autoloading adjustments needed"
      - "Deprecation warnings resolved"
    risks:
      - "Minor performance regression in asset pipeline"
  - branch_id: "partial_failure"
    probability: 0.30
    final_state:
      rails_version: "7.0.8"
      breaking_changes_resolved: true
      tests_passing: false
    key_events:
      - "ActiveRecord callback order changed"
      - "3 test failures in UserService"
    risks:
      - "Subtle behavior changes in model callbacks"
      - "Extended debugging time required"
  - branch_id: "blocked"
    probability: 0.10
    final_state:
      rails_version: "6.1.7"
      upgrade_blocked: true
    key_events:
      - "Incompatible gem: devise_token_auth requires Rails < 7"
    risks:
      - "Upgrade blocked until gem updated"
trajectory:
  - step: 1
    state: { phase: "analysis" }
    changes: ["Identified 12 deprecation warnings", "Found 3 incompatible gems"]
  - step: 2
    state: { phase: "gem_updates" }
    changes: ["Updated 8 gems", "1 gem requires replacement"]
  - step: 3
    state: { phase: "code_changes" }
    changes: ["Modified 15 files for API changes"]
  - step: 4
    state: { phase: "testing" }
    changes: ["Tests executed", "85% passing initially"]
  - step: 5
    state: { phase: "resolution" }
    changes: ["Fixed remaining issues"]
final_state:
  rails_version: "7.0.8"
  breaking_changes_resolved: true
  tests_passing: true
  effort_estimate: "2-3 days"
insights:
  - type: "risk"
    description: "devise_token_auth compatibility is the main blocker"
    severity: "high"
  - type: "opportunity"
    description: "Rails 7 Hotwire enables simpler frontend code"
    severity: "medium"
  - type: "surprise"
    description: "More callback order dependencies than expected"
    severity: "medium"
simulation_meta:
  steps_executed: 5
  branches_explored: 3
  assumptions:
    - "Test suite provides good coverage"
    - "No undocumented monkey patches"
    - "CI environment matches production"
confidence: 0.75
evidence_anchors:
  - "Gemfile:dependencies"
  - "rails upgrade guide:7.0"
  - "gem:devise_token_auth:compatibility"

Example 2: Simulate Failure Scenario

Input:

scenario:
  type: "failure_injection"
  change: "Database becomes unavailable for 5 minutes"
initial_state:
  database: "available"
  cache: "warm"
  queue_depth: 0
steps: 10
explore: "branches"

Output:

outcomes:
  - branch_id: "graceful_degradation"
    probability: 0.40
    final_state:
      service_status: "degraded"
      data_loss: false
      user_impact: "read_only_mode"
    key_events:
      - "Circuit breaker activates at t+30s"
      - "Cache serves stale reads"
      - "Writes queued for retry"
    risks:
      - "Cache expires during outage"
  - branch_id: "cascade_failure"
    probability: 0.35
    final_state:
      service_status: "down"
      data_loss: false
      user_impact: "complete_outage"
    key_events:
      - "Connection pool exhausted at t+60s"
      - "Health checks fail"
      - "Load balancer removes all instances"
    risks:
      - "Recovery requires manual intervention"
  - branch_id: "data_inconsistency"
    probability: 0.25
    final_state:
      service_status: "recovered"
      data_loss: "possible"
      user_impact: "partial_data_loss"
    key_events:
      - "In-flight transactions lost"
      - "Retry logic creates duplicates"
    risks:
      - "Data reconciliation needed"
trajectory:
  - step: 1
    state: { db: "available", errors: 0 }
    changes: []
  - step: 2
    state: { db: "unavailable", errors: "increasing" }
    changes: ["First connection timeout"]
  - step: 3
    state: { db: "unavailable", circuit: "open" }
    changes: ["Circuit breaker triggered"]
final_state:
  database: "available"
  service_status: "recovering"
  queue_depth: 1250
insights:
  - type: "risk"
    description: "No circuit breaker on write path"
    severity: "high"
  - type: "risk"
    description: "Connection pool timeout too long (30s)"
    severity: "medium"
  - type: "opportunity"
    description: "Add read replica failover"
    severity: "medium"
simulation_meta:
  steps_executed: 10
  branches_explored: 3
  assumptions:
    - "Database failure is total, not partial"
    - "No manual intervention during outage"
    - "Cache TTL is 5 minutes"
confidence: 0.65
evidence_anchors:
  - "config/database.yml:pool_settings"
  - "app/services/circuit_breaker.rb"
  - "architecture:failure_modes"

Verification

• [ ] Scenario clearly defined
• [ ] At least one outcome path explored
• [ ] Probabilities assigned to outcomes
• [ ] Key assumptions documented
• [ ] Insights identify actionable findings

Verification tools: Read (to verify model components)

Safety Constraints

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

Capability-specific rules:
- Simulation does not modify real state
- Note when model may be incomplete
- Flag high-uncertainty outcomes
- Do not present simulation as prediction

Composition Patterns

Commonly follows:
- state - State model provides simulation basis
- transition - Transition rules drive simulation
- plan - Simulate plan outcomes before execution

Commonly precedes:
- compare - Compare simulation outcomes
- plan - Inform planning with simulation insights
- critique - Critique designs based on simulation

Anti-patterns:
- Never treat simulation as certainty (use verify for real testing)
- Avoid simulating without state/transition models

Workflow references:
- See workflow_catalog.yaml#world_model_build for simulation in modeling