---
name: value-stream-map
description: Map a construction or design process as a value stream (submittals, RFIs, change orders, payment certificates, material supply, permit approval, prefabrication) - steps, cycle and waiting times, value-added vs not, first-pass yield - compute lead time, process cycle efficiency and the bottleneck, draw it as a Mermaid diagram and compare a future state. Use when the user mentions value stream mapping, VSM, "mapa de flujo de valor", "por qué se demora tanto", a slow approval or procurement process, or wants to redesign a workflow before automating it with AI.
---

# Value stream map

Map before you automate: automating a process that is 80% waiting only makes the waiting faster to report.

## Inputs
- The process and its unit (one RFI, one submittal, one apartment's windows, one payment certificate).
- Steps from trigger to customer, with who does each, the working time and the waiting time before it. Best: timestamps from the log (Procore, Forma/ACC, email, spreadsheet). Otherwise the team's estimates, labelled as such.
- How often each step sends work back (first-pass yield).

## Procedure
1. Walk the process with the people who do it (or read the log); name the customer and the trigger.
2. Write `steps.csv`: `step,owner,cycle_time,wait_before,value_added,first_pass_yield,note` with all times in one unit.
3. Run `python scripts/vsm.py steps.csv --unit days` (add `--demand` and `--period-time` to compare steps with the takt of demand).
4. Read it with the team: share of waiting, longest queue, longest step, rework loops (low first-pass yield), steps no customer would pay for.
5. Design the future state: remove or merge steps, cut queues (batch size, review sessions instead of sequential reviews, standard checklists), fix the rework source. Write `future.csv` and run with `--future future.csv`.
6. Pick where AI really helps in the future state (e.g. pre-checking a submittal against the spec with `submittal-review` before it enters the queue), and where a simple rule or meeting is enough.
7. Plan a small trial with a measure and a date.

## Output
- `vsm.md`: step table, lead time, PCE, bottleneck, timeline, Mermaid diagram, current vs future comparison; plus the trial plan.

## Never
- Never invent times; mark estimates and prefer timestamps.
- Never present the future state as a result before it is tested.
- Never blame a person for a queue; queues come from the process design.