run-simulation

name	run-simulation
description	Create or run simulation features for analyzing work flow through value streams
user-invocable	true
allowed-tools	Read, Write, Edit, Grep, Glob, Bash

Skill: Create Simulation Feature

Add a new simulation or what-if scenario feature.

Usage

/run-simulation <feature-name>

Prerequisites

Create a feature file first using /new-feature that describes:

• What the simulation models
• What parameters users can configure
• What insights users gain from the simulation

Example Feature File

Feature: Work Flow Simulation
  As a team analyzing their process
  I want to simulate work flowing through our value stream
  So that I can identify bottlenecks and queuing problems

  Scenario: Run basic flow simulation
    Given a value stream with 3 steps
    And each step has capacity for 1 item at a time
    When I add 5 work items to the queue
    And run the simulation
    Then I should see items move through each step
    And completed items should appear at the end

  Scenario: Identify bottleneck through simulation
    Given a value stream where step 2 takes twice as long as others
    When I run the simulation with 10 work items
    Then step 2 should show the largest queue buildup
    And it should be highlighted as a bottleneck

  Scenario: Adjust batch size and see impact
    Given a value stream with batch size of 5 at deployment
    When I change batch size to 1
    And run the simulation comparison
    Then I should see reduced lead time in the smaller batch scenario

Architecture

Simulations follow this pattern:

1. Configuration - User sets parameters via UI
2. Engine - Pure functions that calculate state transitions
3. Visualization - React components that display animation
4. Results - Metrics and insights from the simulation run

Implementation Steps

1. Define simulation parameters in src/utils/simulation/{feature}.js
2. Create the simulation engine as pure functions
3. Add configuration UI in src/components/simulation/{Feature}Config.jsx
4. Create visualization component in src/components/simulation/{Feature}Viz.jsx
5. Add results display in src/components/simulation/{Feature}Results.jsx
6. Write thorough tests for the simulation logic

Simulation Engine Pattern

// src/utils/simulation/{feature}.js

/**
 * Initialize simulation state
 * @param {Object} vsm - Value stream map
 * @param {Object} config - Simulation configuration
 * @returns {Object} Initial simulation state
 */
export function initializeSimulation(vsm, config) {
  return {
    currentTick: 0,
    workItems: Array.from({ length: config.workItemCount }, (_, i) => ({
      id: `item-${i}`,
      currentStep: null,
      stepProgress: 0,
      history: []
    })),
    stepStates: new Map(vsm.steps.map(step => [
      step.id,
      { queue: [], processing: null, completed: 0 }
    ])),
    metrics: {
      throughput: 0,
      avgCycleTime: 0,
      maxQueueSize: 0
    }
  };
}

/**
 * Simulate one tick of the system
 * Pure function: returns new state without mutation
 *  {}  - Current simulation state
 *  {}  - Value stream map
 *  {} New simulation state
 */
  () {
  
   newState = {
    ...state,
    : state. + ,
    : [...state.],
    :  (state.)
  };

  
   ( step  vsm.) {
    
    
    
  }

  
  newState. = (newState);

   newState;
}


  () {
   state = (vsm, config);
   history = [state];

   ( i = ; i < config.; i++) {
    state = (state, vsm);
    history.(state);
  }

   {
    : state,
    history,
    : (history, vsm)
  };
}

Visualization Component

// src/components/simulation/{Feature}Viz.jsx

import { useState, useEffect } from 'react';
import PropTypes from 'prop-types';

function {Feature}Viz({ simulationHistory, speed }) {
  const [currentFrame, setCurrentFrame] = useState(0);

  useEffect(() => {
    if (currentFrame >= simulationHistory.length - 1) return;

    const timer = setTimeout(() => {
      setCurrentFrame(f => f + 1);
    }, 1000 / speed);

    return () => clearTimeout(timer);
  }, [currentFrame, simulationHistory.length, speed]);

  const state = simulationHistory[currentFrame];

  return (
    <div data-testid="simulation-viz">
      <div className="simulation-controls">
        <span>Tick: {state.currentTick}</span>
        <button onClick={() => setCurrentFrame(0)}>Reset</>
      
      
        {/* Render work items at their current positions */}
      
    
  );
}

{}. = {
  : ..,
  : .
};

{}. = {
  : 
};

  {};

Key Simulation Concepts

• Tick: One unit of simulation time
• Work Item: An individual unit flowing through the system
• Step State: Current status of a process step (idle, processing, blocked)
• Queue: Work items waiting to enter a step
• Throughput: Items completed per time unit
• Cycle Time: Time for one item to traverse the entire stream