process-mapper

# Process Mapper

Turns "this takes forever and nobody knows why" into a measured map with a
ranked backlog. Most process work fails on two things: it maps what people
describe rather than what runs, and it costs wait-time savings as if they were
labour savings. This skill is built to prevent both.

## When to use this skill

- **A process is slow** and nobody can say which step is responsible
- **Work bounces between teams** and the handoffs are suspected but not measured
- **Rework is high** — submissions get returned, tickets get reopened, orders get corrected
- **Before automating anything** — to check the step should exist at all
- **Onboarding a new team** onto an inherited process nobody has documented
- **An improvement programme needs a backlog** ranked by payback rather than by volume of complaint

## Inputs the skill expects

- Process boundaries: trigger event, terminal state, and the unit that flows through
- Step list with owner (role, not person), touch time, and wait time per step
- Wait times from system timestamps rather than self-report where possible
- Rework rate per step and the step each loop returns to
- System of record per step, to detect re-keying points
- Monthly volume and a loaded hourly cost, for valuing improvements

## Clarify First

Before generating, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Which variant are we mapping, and what share of volume is it?** — mapping every exception produces an unreadable map; mapping a 20% path optimises the wrong process
- [ ] **Where do the wait times come from — timestamps or memory?** — self-reported queue time is understated by 40-70%, which moves the constraint to the wrong step
- [ ] **Is the goal lead time, labour cost, or quality?** — these have different constraints and often opposite fixes
- [ ] **Has the business quantified what faster is worth?** — without their number, cycle-time gains cannot be costed and must be argued separately

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

## Workflows

### Workflow 1 — Capture and measure the process

1. Scope first: agree trigger, terminal, unit, and variant on one page before any detail. Use the SIPOC frame in `assets/process-map-template.md`.
2. Observe the work happening before running a workshop. Observation finds the workaround spreadsheet and the chase email; workshops do not.
3. Pull wait times from system timestamps. Use median and 85th percentile, never mean — process-time distributions have long right tails.
4. Classify each step as value-added, business-value-added, or non-value-added. Test approvals by their rejection rate: below 5% and it is a queue with a job title.
5. Run the analyser and check the modelled lead time against measured end-to-end lead time. A gap above 20% means missing steps or, more often, missing wait.

```bash
python3 business-operations/process-mapper/scripts/process_analyzer.py \
  --input business-operations/process-mapper/assets/sample_process.json \
  --format text
```

### Workflow 2 — Diagnose handoffs and rework loops

1. Run the handoff analyser on the same process file — no separate input needed.
2. Read handoff density first. Above 0.5 owner changes per step, consolidating ownership beats optimising any individual step.
3. Check what share of total wait sits at handoffs. Above 60%, the problem is between teams and no amount of internal team improvement will move it.
4. Treat every system switch as a re-keying and data-loss point, and every cross-team rework loop as a check that belongs upstream of where it fires.
5. Look at ping-pong: an owner visited three or more separate times should own their segment end to end.

```bash
python3 business-operations/process-mapper/scripts/handoff_analyzer.py \
  --input business-operations/process-mapper/assets/sample_process.json \
  --format text
```

### Workflow 3 — Build the improvement backlog

1. Generate opportunities from the findings, applying the improvement hierarchy in order: eliminate, consolidate, parallelise, standardise, automate.
2. Split every saving into `touch_minutes_saved_per_unit` (labour, costed) and `lead_minutes_saved_per_unit` (elapsed, not costed). This split is the discipline that keeps the business case survivable.
3. Supply `annual_cycle_time_value` only when the business has quantified it — that figure is theirs, not the analyst's.
4. Run the scorer and read the tiers. Anything above 20 days of effort is a project needing its own sponsor, not a backlog item.
5. Override payback order in one case: if first-pass yield is below 85%, sequence the rework fixes first regardless of their payback. Flow improvements cannot hold on a process that reworks half its units.

```bash
python3 business-operations/process-mapper/scripts/improvement_scorer.py \
  --input business-operations/process-mapper/assets/sample_opportunities.json \
  --format json
```

## Decision frameworks

### Diagnostic thresholds [PROVEN]

| Signal | Threshold | What it means |
|--------|-----------|---------------|
| Step share of lead time | Above 20% | This is the constraint |
| Wait/touch ratio on a step | Above 3x | A queue, not work |
| Wait/touch ratio | Above 10x | Batch-and-queue scheduling; fix policy, not capacity |
| Rework rate per step | Above 10% | Fix before any speed work |
| First-pass yield end to end | Below 85% | Rework is the dominant cost |
| Handoff density | Above 0.5/step | Fragmented ownership |
| Wait sitting at handoffs | Above 60% | Optimise between teams, not inside them |
| Non-value-added touch time | Above 25% | Eliminate before automating |
| Approval rejection rate | Below 5% | The approval is theatre |

### Process cycle efficiency bands [PROVEN]

PCE = value-added time / lead time, for transactional processes:

| PCE | Band | Situation |
|-----|------|-----------|
| Below 5% | Poor | Un-improved multi-team proces