borghei/Claude-Skills / business-operations/process-mapper
process-mapper
VerifiedMap, measure and improve business processes — SIPOC and swimlane capture, cycle-time and bottleneck analysis, handoff diagnosis, and a payback-ranked improvement backlog. Use when a process is slow, error-prone, or crosses too many teams.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.0 KB |
| assets/process-map-template.md | markdown | 3.4 KB |
| assets/sample_opportunities.json | config | 3.5 KB |
| assets/sample_process.json | config | 3.5 KB |
| references/lean-process-analysis.md | markdown | 11.3 KB |
| references/process-capture-methods.md | markdown | 9.5 KB |
| scripts/handoff_analyzer.py | script | 11.3 KB |
| scripts/improvement_scorer.py | script | 11.2 KB |
| scripts/process_analyzer.py | script | 12.1 KB |
scripts/handoff_analyzer.py
View on GitHub#!/usr/bin/env python3
"""Find handoffs, ping-pong loops and system switches in a process definition.
Handoffs are where transactional processes lose time: each owner change adds a
queue, and each system change adds re-keying and error risk. This tool scores
every handoff, detects owners the work returns to repeatedly, and maps rework
loops that cross team boundaries.
Usage:
python3 handoff_analyzer.py --input sample_process.json
python3 handoff_analyzer.py --input sample_process.json --format json
"""
import argparse
import json
import sys
from pathlib import Path
from typing import Any, Dict, List
# Handoff density above this many owner changes per step signals fragmentation.
HANDOFF_DENSITY_ALERT = 0.5
# A handoff whose receiving step waits longer than this is a hard queue.
HANDOFF_WAIT_ALERT_MIN = 240.0
# Risk score at or above this needs a named owner and a fix date.
HIGH_RISK_SCORE = 6
def build_handoffs(steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Return one record per owner change, scored for delay and failure risk."""
handoffs: List[Dict[str, Any]] = []
for prev, curr in zip(steps, steps[1:]):
from_owner = prev.get("owner", "unassigned")
to_owner = curr.get("owner", "unassigned")
if from_owner == to_owner:
continue
wait = float(curr.get("wait_time_min", 0))
system_switch = prev.get("system") != curr.get("system")
manual_transfer = not bool(curr.get("automated", False))
rework = float(curr.get("rework_rate", 0))
score = 0
reasons: List[str] = []
if wait >= 60:
score += 3 if wait >= HANDOFF_WAIT_ALERT_MIN else 2
reasons.append(f"{wait:.0f} min queue on receipt")
elif wait > 0:
score += 1
if system_switch:
score += 2
reasons.append(f"system change {prev.get('system')} -> {curr.get('system')}")
if manual_transfer:
score += 1
reasons.append("manual transfer")
if rework >= 0.10:
score += 2
reasons.append(f"{rework:.0%} rework on the receiving step")
handoffs.append(
{
"from_step": prev.get("id"),
"to_step": curr.get("id"),
"from_owner": from_owner,
"to_owner": to_owner,
"wait_min": wait,
"system_switch": system_switch,
"manual_transfer": manual_transfer,
"receiving_rework_rate": rework,
"risk_score": score,
"risk_band": "HIGH" if score >= HIGH_RISK_SCORE else ("MEDIUM" if score >= 3 else "LOW"),
"reasons": reasons,
}
)
return handoffs
def find_ping_pong(steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Identify owners the work leaves and later returns to."""
visits: Dict[str, List[int]] = {}
last_owner = None
for i, s in enumerate(steps):
owner = s.get("owner", "unassigned")
if owner != last_owner:
visits.setdefault(owner, []).append(i)
last_owner = owner
results = []
for owner, indices in visits.items():
if len(indices) > 1:
results.append(
{
"owner": owner,
"visit_count": len(indices),
"step_indices": indices,
"note": f"work returns to {owner} {len(indices) - 1} time(s) after leaving",
}
)
return sorted(results, key=lambda r: -r["visit_count"])
def find_rework_loops(steps: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""Map rework loops and flag those crossing an owner boundary."""
id_to_index = {s.get("id"): i for i, s in enumerate(steps)}
loops = []
for i, s in enumerate(steps):
rate = float(s.get("rework_rate", 0))
target = s.get("rework_to")
if rate <= 0 or not target:
continue
start = id_to_index.get(target)
if start is None:
raise ValueError(f"step '{s.get('id')}' has rework_to '{target}' which is not a known step id")
if start > i:
raise ValueError(f"step '{s.get('id')}' loops forward to '{target}'; rework must go backward")
span = steps[start : i + 1]
owners = sorted({x.get("owner", "unassigned") for x in span})
loop_minutes = sum(
float(x.get("process_time_min", 0)) + float(x.get("wait_time_min", 0)) for x in span
)
loops.append(
{
"detected_at_step": s.get("id"),
"returns_to_step": target,
"steps_replayed": len(span),
"owners_involved": owners,
"crosses_owner_boundary": len(owners) > 1,
"rework_rate": rate,
"loop_minutes": round(loop_minutes, 1),
"expected_minutes_per_unit": round(rate * loop_minutes, 1),
}
)
return sorted(loops, key=lambda x: -x["expected_minutes_per_unit"])
def analyse(data: Dict[str, Any]) -> Dict[str, Any]:
"""Produce the full handoff, ping-pong and loop analysis for a process."""
steps = data.get("steps", [])
if not steps:
raise ValueError("input JSON needs a non-empty 'steps' array")
handoffs = build_handoffs(steps)
ping_pong = find_ping_pong(steps)
loops = find_rework_loops(steps)
owners: Dict[str, Dict[str, float]] = {}
for s in steps:
o = s.get("owner", "unassigned")
bucket = owners.setdefault(o, {"steps": 0, "touch_min": 0.0, "wait_min": 0.0})
bucket["steps"] += 1
bucket["touch_min"] += float(s.get("process_time_min", 0))
bucket["wait_min"] += float(s.get("wait_time_min", 0))
handoff_wait = sum(h["wait_min"] for h in handoffs)
total_wait = sum(float(s.get("wait_time_min", 0)) for s in steps)
density = len(handoffs) / len(steps)
handoff_wait_share = round(handoff_wait / total_wait, 3) if total_wait else 0.0
findings: List[str] = []
if density > HANDOFF_DENSITY_ALERT:
findings.append(
f"{len(handoffs)} handoffs across {len(steps)} steps ({density:.2f} per step) — "
"the process is fragmented; consolidating ownership will beat optimising any single step."
)
if handoff_wait_share > 0.6:
findings.append(
f"{handoff_wait_share:.0%} of all wait time sits at handoffs. "
"Target the queues between teams, not the work inside them."
)
for h in handoffs:
if h["risk_band"] == "HIGH":
findings.append(
f"High-risk handoff {h['from_owner']} -> {h['to_owner']} "
f"({h['from_step']} -> {h['to_step']}): " + "; ".join(h["reasons"])
)
for p in ping_pong:
if p["visit_count"] >= 3:
findings.append(
f"{p['owner']} is visited {p['visit_count']} separate times — "
"consolidate their steps or give them end-to-end ownership of the segment."
)
for lp in loops:
if lp["crosses_owner_boundary"]:
findings.append(
f"Cross-team rework loop at '{lp['detected_at_step']}' replaying "
f"{lp['steps_replayed']} steps across {', '.join(lp['owners_involved'])} — "
f"{lp['expected_minutes_per_unit']:.0f} min per unit. Move the check upstream."
)
switches = sum(1 for h in handoffs if h["system_switch"])
if switches:
findings.append(
f"{switches} handoff(s) involve a system change — each is a re-keying and data-loss point."
)
return {
"process_name": data.get("process_name", "unnamed process"),
"step_count": len(steps),
"handoff_count": len(handoffs),
"handoff_density_per_step": round(density, 2),
"handoffs": handoffs,
"wait_at_handoffs_min": round(handoff_wait, 1),
"total_wait_min": round(total_wait, 1),
"handoff_wait_share": handoff_wait_share,
"owner_load": {
k: {
"steps": int(v["steps"]),
"touch_min": round(v["touch_min"], 1),
"wait_min": round(v["wait_min"], 1),
}
for k, v in sorted(owners.items())
},
"ping_pong": ping_pong,
"rework_loops": loops,
"findings": findings,
}
def output(result: Dict[str, Any], fmt: str) -> None:
"""Print the handoff analysis as JSON or a human-readable report."""
if fmt == "json":
print(json.dumps(result, indent=2))
return
print(f"HANDOFF ANALYSIS — {result['process_name']}")
print("=" * 78)
print(
f"{result['handoff_count']} handoffs across {result['step_count']} steps "
f"({result['handoff_density_per_step']} per step) | "
f"{result['handoff_wait_share']:.0%} of wait time is at handoffs"
)
print()
print(f"{'From -> To':<44}{'Wait':>8}{'Sys':>6}{'Score':>7} Band")
print("-" * 78)
for h in result["handoffs"]:
pair = f"{h['from_owner'][:20]} -> {h['to_owner'][:20]}"
print(
f"{pair:<44}{h['wait_min']:>8.0f}{'yes' if h['system_switch'] else 'no':>6}"
f"{h['risk_score']:>7} {h['risk_band']}"
)
print("-" * 78)
print()
print("OWNER LOAD")
for owner, v in result["owner_load"].items():
print(
f" {owner[:22]:<24}{v['steps']:>3} steps{v['touch_min']:>9.0f} min touch"
f"{v['wait_min']:>9.0f} min wait"
)
if result["ping_pong"]:
print()
print("PING-PONG")
for p in result["ping_pong"]:
print(f" {p['owner'][:22]:<24}{p['note']}")
if result["rework_loops"]:
print()
print("REWORK LOOPS")
for lp in result["rework_loops"]:
cross = "cross-team" if lp["crosses_owner_boundary"] else "within-team"
print(
f" {lp['detected_at_step']} -> {lp['returns_to_step']} "
f"{lp['rework_rate']:.0%} x {lp['loop_minutes']:.0f} min = "
f"{lp['expected_minutes_per_unit']:.0f} min/unit ({cross})"
)
if result["findings"]:
print()
print("FINDINGS")
for f in result["findings"]:
print(f" ! {f}")
def main() -> None:
"""Parse arguments, run the handoff analysis, and print the result."""
parser = argparse.ArgumentParser(
description="Find handoffs, ping-pong loops and system switches in a process.",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
parser.add_argument(
"--input",
required=True,
help="Path to a process definition JSON file (see assets/sample_process.json)",
)
parser.add_argument(
"--format", choices=["text", "json"], default="text", help="Output format"
)
args = parser.parse_args()
try:
data = json.loads(Path(args.input).read_text(encoding="utf-8"))
output(analyse(data), args.format)
except FileNotFoundError:
print(f"Error: input file not found: {args.input}", file=sys.stderr)
sys.exit(1)
except json.JSONDecodeError as exc:
print(f"Error: {args.input} is not valid JSON ({exc})", file=sys.stderr)
sys.exit(1)
except (ValueError, KeyError, TypeError) as exc:
print(f"Error: could not analyse handoffs — {exc}", file=sys.stderr)
sys.exit(1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |