From 1e76abd796bc72304a0c278da48e1743f1fbc7ae Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Fri, 3 Jul 2026 15:10:23 -0500 Subject: [PATCH 01/16] Add optional scenario name to label runs in the stats comparison When comparing several simulation runs, the stats columns are all titled by the workload string (e.g. "dev: 1"), which makes runs with the same workload but different workers or WIP limits hard to tell apart. Adds an optional Name field to the form; when filled, it is used as the scenario title. Falls back to the workload string when left blank. Also adds a little top padding to #stats so the selected column's outline is not clipped by the sticky header's shadow. Co-Authored-By: Claude Fable 5 --- index.html | 7 +++++++ src/setup.ts | 2 +- style.css | 4 ++++ 3 files changed, 12 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index af1106b..6de0387 100644 --- a/index.html +++ b/index.html @@ -11,6 +11,13 @@
+
+
+
Name
+ +
+
+
Work per story
diff --git a/src/setup.ts b/src/setup.ts index 36d9c93..2607741 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -85,7 +85,7 @@ function parse(form: HTMLFormElement) { const field = (fieldName: string) => (form.querySelector(`[name="${fieldName}"]`) as HTMLInputElement).value; return parseInput({ - title: field('workload'), + title: field('scenario-name').trim() || field('workload'), workers: field('workers'), workload: field('workload'), wipLimit: field('wip-limit'), diff --git a/style.css b/style.css index 59d760c..cc8e02c 100644 --- a/style.css +++ b/style.css @@ -156,6 +156,10 @@ +#stats { + padding-top: 0.5rem; +} + .scenario { list-style: none; padding: 0; From 5b3619c1de3e8ff5f57b32cf2ed2a50b92838870 Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Fri, 3 Jul 2026 17:00:33 -0500 Subject: [PATCH 02/16] Keep the stats comparison readable: outline clipping and title wrap - #scenarios gets 4px internal padding so the selected column's outline is not clipped by the overflow-auto scroll container (padding outside the container could not fix this). - Scenario titles stay on one line with an ellipsis so a long workload title no longer wraps and misaligns the stat rows against the legend. The full title is available as a tooltip. Co-Authored-By: Claude Fable 5 --- src/setup.ts | 4 +++- style.css | 10 ++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/src/setup.ts b/src/setup.ts index 2607741..7f814e8 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -77,7 +77,9 @@ function createScenarioContainer(scenario: any) { const clone = (template.content.cloneNode(true) as DocumentFragment).querySelector('ul')!; clone.setAttribute('id', `scenario-${scenario.id}`); - clone.querySelector('.scenario-title')!.textContent = scenario.title; + const $title = clone.querySelector('.scenario-title') as HTMLElement; + $title.textContent = scenario.title; + $title.title = scenario.title; return clone } diff --git a/style.css b/style.css index cc8e02c..778627a 100644 --- a/style.css +++ b/style.css @@ -160,6 +160,16 @@ padding-top: 0.5rem; } +#scenarios { + padding: 4px; +} + +.scenario-title { + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + .scenario { list-style: none; padding: 0; From e55707d66789c2b6a9d87d29290acfe27f938176 Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Fri, 3 Jul 2026 17:00:34 -0500 Subject: [PATCH 03/16] Accept worker and skill names case-insensitively Typing "Fullstack" instead of "fullstack" flagged the workers field as invalid, and a capitalized worker would receive no skills at all (the engine looks skills up in lowercase). Worker names and workload keys are now lowercased at the parsing and validation boundary, so any capitalization works. Co-Authored-By: Claude Fable 5 --- src/form-helper.ts | 9 +++++---- src/parsing.ts | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/src/form-helper.ts b/src/form-helper.ts index 8bae3ee..d0a7891 100644 --- a/src/form-helper.ts +++ b/src/form-helper.ts @@ -4,14 +4,15 @@ const validateWorkers = ({workload, workers}: {workload?: string, workers: strin const validateWorkersFormat = () => /^(\s*(\w+)(\+\w+)*\s*)(,\s*(\w+)(\+\w+)*\s*)*$/gm.test(workers); const validateWorkLoadCanBeExecuted = () => { - if (workers.includes('fullstack')) return workers; - if (workers.includes('fs')) return workers; + const workersLC = workers.toLowerCase(); + if (workersLC.includes('fullstack')) return workers; + if (workersLC.includes('fs')) return workers; if (!workload) return false; - const expectedWorkers = workload.split(',') + const expectedWorkers = workload.toLowerCase().split(',') .map(worker => worker.split(':')[0]!.trim()); - return expectedWorkers.every(w => workers.includes(w)) + return expectedWorkers.every(w => workersLC.includes(w)) }; return validateWorkersFormat() && validateWorkLoadCanBeExecuted(); diff --git a/src/parsing.ts b/src/parsing.ts index 184da3e..6ee6d0e 100644 --- a/src/parsing.ts +++ b/src/parsing.ts @@ -30,7 +30,7 @@ function parseWorkers(input: string) { function parseSkills(input: string): string[] { return input .split('+') - .map(skill => skill.trim()); + .map(skill => skill.trim().toLowerCase()); } function parseWorkload(input: string): Record { @@ -42,7 +42,7 @@ function parseWorkload(input: string): Record { .split(":") ) .reduce((work: Record, pair) => { - work[pair[0]!.trim()] = parseInt(pair[1]!.trim()); + work[pair[0]!.trim().toLowerCase()] = parseInt(pair[1]!.trim()); return work; }, {}) } From eff2f2408d172877e6dfe71a51470759695a7a25 Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Fri, 3 Jul 2026 17:18:11 -0500 Subject: [PATCH 04/16] Add saved recipes and a Clear button for live demos Running the same handful of scenarios in front of an audience means retyping (or pasting) workload, workers, WIP limit and story count each time, with a typo risk on every field. - Every run submitted with a Name is now saved as a "recipe" (name + all form fields) in localStorage. Re-running with the same name updates the recipe. - A Recipe dropdown fills the whole form, including the name, from any saved recipe: pick, Run, talk. - A Clear button resets the page for a blank slate; saved recipes survive (they live in localStorage, not the page). Co-Authored-By: Claude Fable 5 --- index.html | 13 +++++++++++++ src/recipes.ts | 37 +++++++++++++++++++++++++++++++++++++ src/setup.ts | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 src/recipes.ts diff --git a/index.html b/index.html index 6de0387..e960a5b 100644 --- a/index.html +++ b/index.html @@ -11,6 +11,15 @@
+
+
+
Recipe
+ +
+
+
Name
@@ -56,6 +65,10 @@
+ +
+ +
diff --git a/src/recipes.ts b/src/recipes.ts new file mode 100644 index 0000000..36d8ade --- /dev/null +++ b/src/recipes.ts @@ -0,0 +1,37 @@ +export type Recipe = { + name: string; + workload: string; + workers: string; + wipLimit: string; + numberOfStories: string; + random: boolean; +}; + +const KEY = 'explaining-flow.recipes'; + +const load = (): Recipe[] => { + try { + return JSON.parse(localStorage.getItem(KEY) || '[]'); + } catch { + return []; + } +}; + +const save = (recipes: Recipe[]) => localStorage.setItem(KEY, JSON.stringify(recipes)); + +const all = (): Recipe[] => load(); + +const find = (name: string): Recipe | undefined => load().find(r => r.name === name); + +const upsert = (recipe: Recipe) => { + if (!recipe.name.trim()) return; + const recipes = load(); + const index = recipes.findIndex(r => r.name === recipe.name); + if (index >= 0) recipes[index] = recipe; + else recipes.push(recipe); + save(recipes); +}; + +const remove = (name: string) => save(load().filter(r => r.name !== name)); + +export { all, find, upsert, remove }; diff --git a/src/setup.ts b/src/setup.ts index 7f814e8..ebe5aca 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -14,6 +14,7 @@ import { parseInput } from './parsing'; import { Chart } from 'chart.js'; import crosshairPlugin from './crosshair'; import * as FormHelper from './form-helper'; +import * as Recipes from './recipes'; import { initialize as initBoardTimeline, getState as getBoardTimelineState, restoreState as restoreBoardTimelineState } from './boardTimeline'; Chart.register(crosshairPlugin); @@ -100,14 +101,62 @@ function parseScenario(event: Event) { return Scenario(parse(event.target as HTMLFormElement)); } +const $field = (id: string) => document.getElementById(id) as HTMLInputElement; + +function refreshRecipeDropdown() { + const $select = document.getElementById('recipe-select') as HTMLSelectElement | null; + if (!$select) return; + $select.innerHTML = ''; + Recipes.all().forEach(recipe => { + const option = document.createElement('option'); + option.value = recipe.name; + option.textContent = recipe.name; + $select.appendChild(option); + }); +} + +function fillFormFromRecipe(name: string) { + const recipe = Recipes.find(name); + if (!recipe) return; + $field('scenario-name').value = recipe.name; + $field('workload').value = recipe.workload; + $field('workers').value = recipe.workers; + $field('wip-limit').value = recipe.wipLimit; + $field('numberOfStories').value = recipe.numberOfStories; + $field('random').checked = recipe.random; +} + +function saveRecipeFromForm() { + Recipes.upsert({ + name: $field('scenario-name').value.trim(), + workload: $field('workload').value, + workers: $field('workers').value, + wipLimit: $field('wip-limit').value, + numberOfStories: $field('numberOfStories').value, + random: $field('random').checked, + }); + refreshRecipeDropdown(); +} + document.addEventListener('DOMContentLoaded', () => { const form = FormHelper.initialize(); + refreshRecipeDropdown(); + + document.getElementById('recipe-select')! + .addEventListener('change', (event: Event) => { + fillFormFromRecipe((event.target as HTMLSelectElement).value); + }); + + document.getElementById('clear-runs')! + .addEventListener('click', () => window.location.reload()); + document.getElementById('new-scenario')! .addEventListener('submit', (event: Event) => { event.preventDefault() if(!form?.isValid()) return; + saveRecipeFromForm(); const scenario = parseScenario(event); const $container = createScenarioContainer(scenario); const $scenarios = document.getElementById('scenarios')!; From fd3353bea149791854ee3c65df2a75e5e974fa8d Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 10:32:10 -0500 Subject: [PATCH 05/16] Cap the stats comparison at a fixed-height scrollable frame Large teams (4x/8x) produce dozens of worker-utilization rows that shoved the animation far down the page, held there by the tallest column. The scenarios frame now caps at 480px (fits a 2x team, ~14 workers, without scrolling) and scrolls vertically inside itself; the board below stays put regardless of team size. Co-Authored-By: Claude Fable 5 --- style.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/style.css b/style.css index 778627a..ffb2a0a 100644 --- a/style.css +++ b/style.css @@ -162,6 +162,12 @@ #scenarios { padding: 4px; + /* Fixed-height frame: tall enough to show a 2x team (~14 worker rows + + the stat rows) without scrolling. Taller scenario columns scroll + vertically INSIDE this frame instead of shoving the animation down + the page — the board below stays put no matter how big a team gets. */ + max-height: 480px; + overflow-y: auto; } .scenario-title { From 87e366a02571ed9d475cb6104085726bbfaf2146 Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 10:39:00 -0500 Subject: [PATCH 06/16] Add a delete button for the selected recipe Recipes.remove existed with no UI. An outline-danger x next to the Recipe dropdown: disabled until a recipe is selected, deletes exactly that one, re-disables after. Overwrite-by-name (upsert on Run) remains the way to update a recipe in place. Co-Authored-By: Claude Fable 5 --- index.html | 2 ++ src/setup.ts | 21 +++++++++++++++++---- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index e960a5b..19fe80d 100644 --- a/index.html +++ b/index.html @@ -17,6 +17,8 @@ +
diff --git a/src/setup.ts b/src/setup.ts index ebe5aca..49dc6e8 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -143,10 +143,23 @@ document.addEventListener('DOMContentLoaded', () => { refreshRecipeDropdown(); - document.getElementById('recipe-select')! - .addEventListener('change', (event: Event) => { - fillFormFromRecipe((event.target as HTMLSelectElement).value); - }); + const $recipeSelect = document.getElementById('recipe-select') as HTMLSelectElement; + const $deleteRecipe = document.getElementById('delete-recipe') as HTMLButtonElement; + + $recipeSelect.addEventListener('change', (event: Event) => { + const name = (event.target as HTMLSelectElement).value; + fillFormFromRecipe(name); + $deleteRecipe.disabled = !name; + }); + + $deleteRecipe.addEventListener('click', () => { + const name = $recipeSelect.value; + if (!name) return; + Recipes.remove(name); + refreshRecipeDropdown(); + $recipeSelect.value = ''; + $deleteRecipe.disabled = true; + }); document.getElementById('clear-runs')! .addEventListener('click', () => window.location.reload()); From d47c868589bd52c9d94d99d31163244e4d0b6a9a Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 13:13:38 -0500 Subject: [PATCH 07/16] readme: point at this fork's live site and clone URL, credit upstream MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit (Fork-identity change — must be dropped from any upstream PR.) Co-Authored-By: Claude Fable 5 --- readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 3898ecb..d30cd86 100644 --- a/readme.md +++ b/readme.md @@ -9,11 +9,11 @@ The measurements you get for each simulation are: Stakeholders and customers typically worry about throughput and cycle time. Throughput indicates how efficient a team is. Cycle Time indicates how long stakeholders have to wait for their ideas to be implemented, once work starts. ## Using the simulator -You can use the [online simulator](https://michelgrootjans.github.io/explaining-flow/) +You can use the [online simulator](https://hallmansm.github.io/explaining-flow/) (this fork, with scenario names and saved recipes — [Michel Grootjans' original](https://github.com/michelgrootjans/explaining-flow) is the upstream project) ...or you can run it locally: ```shell -git clone git@github.com:michelgrootjans/explaining-flow.git +git clone https://github.com/hallmansm/explaining-flow.git cd explaining-flow npm install npm run dev From f6bcdcb5faa76ca932cbbe67057356547004fd01 Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 13:57:27 -0500 Subject: [PATCH 08/16] Bake the Banana Software Company recipes in as first-visit defaults MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eleven demo recipes (Base Team through the WIP+cross-skill+batch combos, dev time 8 full-batch / 4 cut-batch) seed into localStorage on first visit only — the key having never been written. Users can delete any or all (an emptied list stays empty) and add their own. Co-Authored-By: Claude Fable 5 --- src/recipes.ts | 24 +++++++++++++++++++++++- src/setup.ts | 1 + 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/recipes.ts b/src/recipes.ts index 36d8ade..9d94013 100644 --- a/src/recipes.ts +++ b/src/recipes.ts @@ -9,6 +9,23 @@ export type Recipe = { const KEY = 'explaining-flow.recipes'; +// The Banana Software Company demo set — baked in so a fresh visitor gets a +// ready-made lecture series. Seeded only on first visit (see seedDefaults): +// deleting them stores '[]', which is respected — they don't resurrect. +const DEFAULT_RECIPES: Recipe[] = [ + { name: 'Base Team', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po, ui, ui, dev, dev, dev, qa', wipLimit: '', numberOfStories: '100', random: true }, + { name: '2x People', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa', wipLimit: '', numberOfStories: '100', random: true }, + { name: '4x People', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa', wipLimit: '', numberOfStories: '100', random: true }, + { name: '8x People', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa, po, ui, ui, dev, dev, dev, qa', wipLimit: '', numberOfStories: '100', random: true }, + { name: 'WIP throttling only', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po, ui, ui, dev, dev, dev, qa', wipLimit: '7', numberOfStories: '100', random: true }, + { name: 'Cross-skilling only', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po+qa, po+ui, ui+dev, ui+qa, dev+ui, dev+qa, qa+ui', wipLimit: '', numberOfStories: '100', random: true }, + { name: 'Cut Batch only', workload: 'po: 1, ui: 2, dev: 4, qa: 1', workers: 'po, ui, ui, dev, dev, dev, qa', wipLimit: '', numberOfStories: '200', random: true }, + { name: 'WIP + cx2 skill + batch', workload: 'po: 1, ui: 2, dev: 4, qa: 1', workers: 'po+qa, po+ui, ui+dev, ui+qa, dev+ui, dev+qa, qa+ui', wipLimit: '7', numberOfStories: '200', random: true }, + { name: 'WIP + cx3 skill + batch', workload: 'po: 1, ui: 2, dev: 4, qa: 1', workers: 'po+qa+ui, po+ui+dev, ui+dev+po, ui+qa+po, dev+ui+qa, dev+qa+po, qa+ui+dev', wipLimit: '7', numberOfStories: '200', random: true }, + { name: 'WIP + fullstack + batch', workload: 'po: 1, ui: 2, dev: 4, qa: 1', workers: 'fullstack, fullstack, fullstack, fullstack, fullstack, fullstack, fullstack', wipLimit: '7', numberOfStories: '200', random: true }, + { name: 'Base Team (noVar)', workload: 'po: 2, ui: 4, dev: 8, qa: 2', workers: 'po, ui, ui, dev, dev, dev, qa', wipLimit: '', numberOfStories: '100', random: false }, +]; + const load = (): Recipe[] => { try { return JSON.parse(localStorage.getItem(KEY) || '[]'); @@ -34,4 +51,9 @@ const upsert = (recipe: Recipe) => { const remove = (name: string) => save(load().filter(r => r.name !== name)); -export { all, find, upsert, remove }; +// First visit only: the key has never been written, so bake in the demo set. +const seedDefaults = () => { + if (localStorage.getItem(KEY) === null) save(DEFAULT_RECIPES); +}; + +export { all, find, upsert, remove, seedDefaults, DEFAULT_RECIPES }; diff --git a/src/setup.ts b/src/setup.ts index 49dc6e8..aa620b0 100644 --- a/src/setup.ts +++ b/src/setup.ts @@ -141,6 +141,7 @@ function saveRecipeFromForm() { document.addEventListener('DOMContentLoaded', () => { const form = FormHelper.initialize(); + Recipes.seedDefaults(); refreshRecipeDropdown(); const $recipeSelect = document.getElementById('recipe-select') as HTMLSelectElement; From 3641aed5a25cae82c880de8799aeb5e85d9ac42c Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 14:10:27 -0500 Subject: [PATCH 09/16] Rewrite readme for the fork: the Banana Software Company experiment series MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Steve's argument in readme form: baseline, buy-capacity (2x/4x/8x and throughput-per-expense), the three free levers solo, the combos that beat 2x payroll at 1x cost, and the noVar control. Fork additions listed, rework-sim linked as the companion, Michel credited as concept/model/original implementation, CC BY 4.0 retained. (Fork-identity change — drop from any upstream PR.) Co-Authored-By: Claude Fable 5 --- readme.md | 288 ++++++++---------------------------------------------- 1 file changed, 42 insertions(+), 246 deletions(-) diff --git a/readme.md b/readme.md index d30cd86..06c6b28 100644 --- a/readme.md +++ b/readme.md @@ -1,273 +1,69 @@ -# Kanban simulator -With this project, you can simulate team structure and see the effect on your team's efficiency and effectiveness. +# Flow Simulator — team topology experiments you can run -The measurements you get for each simulation are: -- Throughput: the number of stories the team finishes per unit of time. Typically referred to as team velocity. -- Cycle Time: the average time taken from start to finish for a story -- WIP: the number of items in progress, started, but not done +Every argument about team structure eventually collapses into dueling anecdotes: specialists vs. cross-skilled, more people vs. better flow, big batches vs. small. This simulator ends the anecdotes. Configure a team, press Run, and watch the physics — throughput, cycle time, and WIP, measured live while animated work items move across a board. -Stakeholders and customers typically worry about throughput and cycle time. Throughput indicates how efficient a team is. Cycle Time indicates how long stakeholders have to wait for their ideas to be implemented, once work starts. +**Run it here: https://hallmansm.github.io/explaining-flow/** — no install, and it comes pre-loaded with a full experiment series (below). -## Using the simulator -You can use the [online simulator](https://hallmansm.github.io/explaining-flow/) (this fork, with scenario names and saved recipes — [Michel Grootjans' original](https://github.com/michelgrootjans/explaining-flow) is the upstream project) +This is a fork of [Michel Grootjans' explaining-flow](https://github.com/michelgrootjans/explaining-flow), extended for live demos and coaching sessions. His original readme includes an excellent scenario-by-scenario lightning talk that remains the best gentle introduction to the tool's ideas. -...or you can run it locally: -```shell -git clone https://github.com/hallmansm/explaining-flow.git -cd explaining-flow -npm install -npm run dev -``` - -Then open [http://localhost:5173](http://localhost:5173) in your browser. - -## My lightning talk -I'd like to share a few simulations showing the effects of team flow. -These simulations show the different scenarios I run to illustrate the need to understand team flow. - -The stats we're interested in are: -- **Throughput**: this is what is typically measured under the name _velocity_. It's the number of user stories finished per unit of time. -- **Cycle time**: the time taken for each story from the moment it has been taken out of the _todo_ column until it reaches the _done_ column. -- **WIP**: Work In Progress. The number of user stories _in flight_. These stories have been started but are not done yet. - ### A single developer working on a predictable backlog -In this predictable scenario, a single developer works on 50 stories. Each story takes exactly 1 day to complete. So we expect a throughput of `1` story per day. We expect a cycle time of `1` since each story will be in progress for exactly 1 day. This means that we'll have an average of `1` story in progress at any given time. - -**Input** -- Work per story: `dev: 1` -- Workers: `dev` - -**Expected Results** - - Throughput: **1 story/day** - - Cycle time: **1 day per story** - - WIP: **1 story** - -### A single developer working on a backlog with some randomness -The developer now spends 1 day _on average_ for each story. -This slight change shows that throughput and cycle time move in opposite directions. -This is a direct illustration of [Little's law](https://en.wikipedia.org/wiki/Little%27s_law) which states that in a stable system, `throughput * cycle time = WIP`. This formula will be applicable to all the simulations. - -**Input** -- Work per story: `dev: 1` -- Workers: `dev` -- Variable work: ☑️ - -**Expected Results** -- Throughput: **1 story/day** -- Cycle time: **1 day per story** -- WIP: **1 story** - -### Handover from development to QA -Now both development and qa will spend 1 day _on average_ for each story. - -We expect the cycle time to be 2 on average now: 1 day of development, 1 day of qa. We also expect a Throughput of 1 story per day. - -However, if the simulation runs for long enough, a queue will start to appear between dev and qa, adding to the cycle time of the stories waiting in the queue. -The reason is simple: As long as qa works faster than dev, everything will run smoothly. Once development starts going faster than qa, its output will wait in the queue. - -**Input** -- Work per story: **dev: 1, qa: 1** -- Workers: **dev, qa** -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.85 stories/day** -- Cycle time: **3 days per story** -- WIP: **about 2-3with peaks up to 5** - -### Adding UX to the process -Let's accelerate the simulation. This allows us to see patterns we wouldn't recognise in the slow daily movements of stories on a board. From now on, we'll simulate with 200 user stories. - -Ux, development and qa will each spend 2 days _on average_ for each story. So each story will have 6 days of work on average (2 ux + 2 dev + 2 qa). - -**Input** -- Work per story: **ux: 2, dev: 2, qa: 2** -- Workers: **ux, dev, qa** -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.45 stories/day** -- Cycle time: **20 days per story** -- WIP: **9 stories with peaks of 16** - -### Let's stack the deck to make development the slowest in the process -We're now going to shift the effort a little. The total amount of work for each story is still 6, but the distribution is now: -- **1** day of ux on average -- **3** days of dev on average -- **2** days of qa on average - -The ideal cycle time is still 6 days (1 + 3 + 2). - -Predictably, a big queue will appear in front of the dev column as dev has three times as much work as ux. The average velocity will go down significantly, and the cycle time will start to skyrocket. - -**Input** -- Work per story: **ux: 1, dev: 3, qa: 2** -- Workers: `ux, dev, qa` -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.30 stories/day** -- Cycle time: **200 days per story** -- WIP: **about 60 with a peak of 120** - -This is bad. The low velocity and high cycle time will make customers very unhappy. Let me remind you that each work item takes 6 days of work on average. Because they wait in a queue for most of their lifecycle, it takes 200 days on average to go from start to finish. This is one of the reasons why the amount of work for a task has no correlation to when it will be finished. - -How can we change the team structure to improve this? - -### Let's add an extra developer -The usual reflex at this point is to add developers to speed things up. This will obviously raise the daily cost of the team. What would be the expected benefit? Twice the throughput? Let's try that out in the next simulation. +## What it measures -**Input** -- Work per story: `ux: 1, dev: 3, qa: 2` -- Workers: ux, **dev, dev**, qa -- Variable work: ☑️ +- **Throughput** — stories finished per day. What velocity wishes it were. +- **Cycle time** — elapsed days from started to done, per story. The only number your customer feels. +- **WIP** — stories in flight: started, not done. -**Example Results** -- Throughput: **0.45 stories/day** -- Cycle time: **100 days per story** -- WIP: **about 50 with a peak of 100** +The three obey [Little's law](https://en.wikipedia.org/wiki/Little%27s_law) (`WIP = throughput × cycle time`) in every scenario — watching that hold while everything else changes is half the education. -We have an improvement in throughput, but it's not the doubling we expected. Cycle time halved but is still disastrous. +## The Banana Software Company experiment series -### Let's add an extra developer -Since adding a developer improved matters, let's try by adding yet another developer +The Recipe dropdown ships pre-loaded with eleven scenarios. They're a sequence, not a grab bag — run them in order and you get the whole argument: -**Input** -- Work per story: **`ux: 1, dev: 3, qa: 2`** -- Workers: ux, **dev, dev, dev**, qa -- Variable work: ☑️ +| # | Recipe | The question it answers | +|---|--------|------------------------| +| 1 | **Base Team** | The baseline: 7 people (po, 2×ui, 3×dev, qa), specialists only, unlimited WIP. Watch the queues form between roles. | +| 2–4 | **2x / 4x / 8x People** | "We need more people." Buy the same team twice, four times, eight times over. Throughput rises — but divide it by payroll and watch **throughput-per-expense** fall. Capacity scales linearly; coordination doesn't. | +| 5 | **WIP throttling only** | One free change: cap work in flight at 7. Same people, same cost. Cycle time drops hard; throughput barely moves. | +| 6 | **Cross-skilling only** | One free change: every person carries a second skill. Handoffs stop blocking; idle time converts to flow. | +| 7 | **Cut Batch only** | One free change: halve the story size (twice the stories). Smaller batches, faster feedback, smoother flow. | +| 8–10 | **WIP + cross-skill + batch combos** | The free levers together — two skills, then three skills, then full-stack, each with WIP capped and batches cut. In typical runs the combos **beat the 2x-payroll team on throughput and crush it on cycle time — at 1x cost.** This is the point of the whole series. | +| 11 | **Base Team (noVar)** | The control: baseline with variability off. Compare against #1 to see what randomness alone costs — queues form even when averages say they shouldn't. | -**Example Results** -- Throughput: **0.45 stories/day** -- Cycle time: **100 days per story** -- WIP: **about 50 with a peak of 100** +Recipes are saved in your browser (localStorage): edit one and re-run under the same name to update it, hit **×** to delete one, name a new configuration to add your own. Clearing them is permanent for your browser — fresh visitors always start with the full set. -Adding an extra developer had absolutely no effect on throughput or cycle time. This was obviously a bad strategy +## Run it locally -### Let's go back to the original team of 3 and introduce a WIP-limit instead -We will simulate with the same team from scenario 5, but introduce a WIP-limit of 10. This means that no-one is allowed to start a new story as long as there are 10 stories _in flight_. - -**Input** -- Work per story: **`ux: 1, dev: 3, qa: 2`** -- Workers: `ux, dev, qa` -- WIP-limit: **10** -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.30 stories/day** -- Cycle time: **30 days per story** -- WIP: **10 stories** - -With no extra cost, our throughput was unaffected, while our cycle time went from 200 days to 30 days. - -### Improve even more -Since limiting WIP works so well, why not limit it to 5? - -**Input** -- Work per story: **`ux: 1, dev: 3, qa: 2`** -- Workers: `ux, dev, qa` -- WIP-limit: **5** -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.30 stories/day** -- Cycle time: **15 days per story** -- WIP: **5 stories** - -Again, with no extra cost, our throughput was unaffected, while our cycle time halved yet again. - -### But you can go too far -Let's try limiting WIP to 2 now. - -**Input** -- Work per story: **`ux: 1, dev: 3, qa: 2`** -- Workers: `ux, dev, qa` -- WIP-limit: **2** -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.25 stories/day** -- Cycle time: **7 days per story** -- WIP: **2 stories** - -Now we start to see a drop in throughput. This might be a good tradeoff depending on your situation. If you care more about rapid feedback than feature delivery speed, you might choose this configuration. - -If you prefer higher throughput with longer feedback cycles, you went too far in limiting WIP. - -### Introducing multidisciplinary team members -Now that we control our cycle time, is there anything we could do to improve the throughput while keeping lead time low? Let's introduce a tester that can also develop. - -**Input** -- Work per story: **`ux: 1, dev: 3, qa: 2`** -- Workers: ux, dev, **qa+dev** -- WIP-limit: `5` -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.38 stories/day** -- Cycle time: **15 days per story** -- WIP: **5 stories** - -Now the throughput is higher. A throughput improvement from `0.30` to `0.38` means we finished our project of 200 work items in about 530 days instead of about 640 days. - -### The best solution: full stack developers -**Input** -- Work per story: **`ux: 1, dev: 3, qa: 2`** -- Workers: `fullstack, fullstack, fullstack` -- WIP-limit: `` -- Variable work: ☑️ - -**Example Results** -- Throughput: **0.47 stories/day** -- Cycle time: **6.2 days per story** -- WIP: **3 stories** - -The throughput is approximately the same as scenario 6, without the cost of the extra developer. The cycle time is now very close to the ideal 6. - -This is the *ideal* situation, and will probably never be reached. Notice how the WIP is limited naturally by the number of team members. - -### Conclusion -First: notice that [Little's law](https://en.wikipedia.org/wiki/Little%27s_law) applies to every scenario we saw: -`throughput * cycle time = WIP` on average values. - -The ideal situation is to have a team of only full-stack developers. You will probably never reach this state. However, you can still aim for this state: - -Start by introducing WIP limits. When the WIP limit has been reached, some team members will have nothing to do. Try to encourage [swarming](https://blog.crisp.se/2009/06/26/henrikkniberg). Team members will then learn new skills and evolve towards becoming a full-stack developer. This will in turn improve the total throughput and cycle time. +```shell +git clone https://github.com/hallmansm/explaining-flow.git +cd explaining-flow +npm install +npm run dev +``` -## Other experiments to try: -Experiment with some hybrid setups and think about why some of these are better than others. For example, which worker setup do you expect to be better: `fullstack, dev, qa`, `ux, fullstack, qa` or `ux, dev, fullstack`? Verify your assumptions by running the simulation. +Then open [http://localhost:5173](http://localhost:5173). +## What this fork adds -You could try to add architecture, analysis, devops, ... I'm sure you'll quickly realize that the more handovers you introduce, the less effective the setup will become. +- **Scenario names** — label runs so five-deep comparisons stay readable +- **Saved recipes** — the dropdown, with update-in-place, delete, and the baked-in demo series +- **A Clear button** — reset runs and charts between audiences, keeping recipes +- **A stable stats frame** — big teams (4x/8x) no longer shove the animation off-screen; the comparison table scrolls in place +- Case-insensitive worker/skill parsing, and assorted demo-hardening fixes -## Roadmap -This project is written in a RDD fashion: Readme Driven Development. This means that this readme is the only feature tracking tool I'm using. +## Companion simulator -### Todo +This sim has no rework loop — quality is assumed. For the other half of the story, the [Rework Backwash simulator](https://hallmansm.github.io/rework-sim/) shows what a defect rate does to a single team's flow: why 33% rework isn't "33% slower" but a queueing cliff. -I welcome suggestions, especially if they come in the form of a pull request. -- Introduce a cumulative flow diagram -- Introduce quality, rework, bugs, collaboration, learning, ... -- Introduce [swarming](https://blog.crisp.se/2009/06/26/henrikkniberg) -- Introduce pairing -- Introduce #mobprogramming -- Introduce epics: one big epic goes through architecture and analysis, then generates a bunch of smaller stories +## Credits -### Done -- Make a working board -- Have a skill set per developer -- Randomize workload per story -- Randomize skill level for each developer -- Add a graph for cycle times, throughput and WIP -- Introduce WIP limits -- Add stats for workers -- Allow multiple developers with the same skill set -- Compare 2 simulations +Concept, model, and the original implementation: [Michel Grootjans](https://github.com/michelgrootjans/explaining-flow). Fork maintained by Steve Hallman ([The Agile Couch](https://theagilecouch.com)), with Claude doing the typing. # License + Shield: [![CC BY 4.0][cc-by-shield]][cc-by] This work is licensed under a -[Creative Commons Attribution 4.0 International License][cc-by]. +[Creative Commons Attribution 4.0 International License][cc-by], +same as the upstream project it derives from. [![CC BY 4.0][cc-by-image]][cc-by] From 74b13599d640ca9a2ca22426deca494e38bfdfec Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 14:13:07 -0500 Subject: [PATCH 10/16] Readme: narrated walkthrough of the recipe series, in dropdown order Each scenario gets its why and its watch-for; the combos close as a skill ladder (2 -> 3 -> 4 skills per person, all with WIP capped and batches cut) against the buying-capacity strategy. Co-Authored-By: Claude Fable 5 --- readme.md | 60 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 11 deletions(-) diff --git a/readme.md b/readme.md index 06c6b28..19e5639 100644 --- a/readme.md +++ b/readme.md @@ -16,17 +16,55 @@ The three obey [Little's law](https://en.wikipedia.org/wiki/Little%27s_law) (`WI ## The Banana Software Company experiment series -The Recipe dropdown ships pre-loaded with eleven scenarios. They're a sequence, not a grab bag — run them in order and you get the whole argument: - -| # | Recipe | The question it answers | -|---|--------|------------------------| -| 1 | **Base Team** | The baseline: 7 people (po, 2×ui, 3×dev, qa), specialists only, unlimited WIP. Watch the queues form between roles. | -| 2–4 | **2x / 4x / 8x People** | "We need more people." Buy the same team twice, four times, eight times over. Throughput rises — but divide it by payroll and watch **throughput-per-expense** fall. Capacity scales linearly; coordination doesn't. | -| 5 | **WIP throttling only** | One free change: cap work in flight at 7. Same people, same cost. Cycle time drops hard; throughput barely moves. | -| 6 | **Cross-skilling only** | One free change: every person carries a second skill. Handoffs stop blocking; idle time converts to flow. | -| 7 | **Cut Batch only** | One free change: halve the story size (twice the stories). Smaller batches, faster feedback, smoother flow. | -| 8–10 | **WIP + cross-skill + batch combos** | The free levers together — two skills, then three skills, then full-stack, each with WIP capped and batches cut. In typical runs the combos **beat the 2x-payroll team on throughput and crush it on cycle time — at 1x cost.** This is the point of the whole series. | -| 11 | **Base Team (noVar)** | The control: baseline with variability off. Compare against #1 to see what randomness alone costs — queues form even when averages say they shouldn't. | +The Recipe dropdown ships pre-loaded with eleven scenarios. They're a sequence, not a grab bag — pick each one, press Run, and read the walkthrough below as you go. Every scenario exists to answer one question, and the columns accumulate in the stats table so you can compare as you climb. + +### 1. Base Team — the org chart everyone starts with + +Seven people: a product owner, two UI designers, three developers, one tester. Each story needs all four specialties in order (po → ui → dev → qa), work per story averages po: 2, ui: 4, dev: 8, qa: 2, and nothing limits how much gets started. This is a completely normal, reasonably staffed team — which is the point. + +**Watch:** queues pile up between the specialties while everyone stays busy. Cycle time runs far beyond the ~16 days of actual work per story, because most of a story's life is spent waiting for the *next* specialist, not being worked. These are the baseline numbers everything else has to beat. + +### 2–4. 2x, 4x, 8x People — buying capacity + +The reflexive fix: "we need more people." These three scenarios buy the exact same team again — twice over, four times, eight times. Payroll scales perfectly linearly. + +**Watch:** throughput rises, but never by the multiple you paid for — divide throughput by team cost and **throughput-per-expense falls with every hire**. And the queues never leave; they just get bigger absolute numbers flowing into them. Capacity was never the constraint, so buying capacity buys disappointment at scale. This is the strategy the rest of the series competes against. + +### 5. WIP throttling only — the first free lever + +Back to the original seven people. One change, costing zero dollars: no more than 7 stories may be in flight at once — when the board is full, nobody starts anything new; they finish something instead. + +**Watch:** cycle time collapses while throughput barely moves. The work didn't speed up — the *waiting* was cut, because the queue between specialties was self-inflicted inventory. Stop starting, start finishing, priced: free. + +### 6. Cross-skilling only — the second free lever + +Original seven again, unlimited WIP, but now every person carries **two skills** (po+qa, ui+dev, dev+qa, …). No hires — the same humans, more versatile. + +**Watch:** the handoff blocking dissolves. When a story needs a tester and the tester is busy, someone else who *can* test picks it up — work routes to the best available person instead of waiting for the one designated specialist. Idle time converts directly into flow. + +### 7. Cut Batch only — the third free lever + +Original seven, specialists, unlimited WIP — but every story is sliced in half (work per item drops to po: 1, ui: 2, dev: 4, qa: 1, and there are twice as many items for the same total work). + +**Watch:** the same amount of work flows noticeably smoother in smaller pieces. Queues form later and drain faster, feedback arrives sooner, and variance hurts less because each individual item risks less. Nothing about the team changed — only the size of the units of work. + +### 8–10. The combos — stacking all three levers + +Now the levers get combined, and the only thing that climbs from scenario to scenario is **how many skills each person carries**: + +- **WIP + cx2 skill + batch** — two-skilled people, WIP capped at 7, stories cut in half +- **WIP + cx3 skill + batch** — three-skilled people, same cap, same small batches +- **WIP + fullstack + batch** — four-skilled people (every skill), same cap, same batches + +**Watch:** each rung of the skill ladder raises throughput and tightens cycle time further, because every additional skill per person removes another class of "waiting for the right specialist." Then put the final column next to **2x People**: in typical runs the full combo **matches or beats the double-payroll team on throughput and crushes it on cycle time — with the original seven people.** That comparison is the entire series in one glance: the levers that cost nothing outperform the lever that cost a second payroll. + +### 11. Base Team (noVar) — the control + +The baseline team once more, but with Variable work switched off: every task takes exactly its average. Compare against scenario 1. + +**Watch:** how much better everything runs on *identical averages*. The difference between this and scenario 1 is the pure cost of randomness — queues form under variability even when the arithmetic says they shouldn't, which is why plans built on averages fail. (Goldratt called it dependent events plus statistical fluctuations; your Gantt chart calls it nothing, which is the problem.) + +--- Recipes are saved in your browser (localStorage): edit one and re-run under the same name to update it, hit **×** to delete one, name a new configuration to add your own. Clearing them is permanent for your browser — fresh visitors always start with the full set. From e9c26e855b1965619bb72cbc355b742752b7ccfe Mon Sep 17 00:00:00 2001 From: Steve Hallman <49403511+hallmansm@users.noreply.github.com> Date: Sat, 4 Jul 2026 14:18:04 -0500 Subject: [PATCH 11/16] Team cost: price tag on every scenario column MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'Team member cost' input beside Run (default $100,000). Each run's column now opens with Team cost — headcount × cost, snapshotted at Run — in a bold money-green row above Throughput. The 2x/4x/8x columns finally wear their price: throughput-per-expense at a glance. Co-Authored-By: Claude Fable 5 --- index.html | 11 +++++++++++ src/setup.ts | 6 ++++++ style.css | 6 ++++++ 3 files changed, 23 insertions(+) diff --git a/index.html b/index.html index 19fe80d..aefc427 100644 --- a/index.html +++ b/index.html @@ -68,6 +68,15 @@
+
+
+
Team member cost
+ +
+
+
@@ -81,6 +90,7 @@
  •  
    • +
  • Team cost
  • Throughput
  • Cycle Time
  • WIP
    • @@ -116,6 +126,7 @@