git:20260727.7ba66d5 to git:20260810.be07f23

---

name: process-mapping

---

# Skill: process-mapping

Produces an **internal business process map** — the inside-out sibling of `journey-mapping`. Where the journey skill maps what a customer experiences frontstage and outside-in, this skill maps what the organisation does backstage and inside-out: the actors, the handoffs, the decision gates, the waste, and the target state. The method is anchored on the APQC L3 process (named flow: trigger → outcome → roles → steps), decomposed to L4 activities (cross-functional handoffs and decision gates — the swimlane content). L5 tasks are work-instruction territory and are out of scope here. See `references/process-mapping.md`.

**Inputs:** job aids, SOPs, or work instructions (primary); SME knowledge elicited inline when no documents are present. Both are standalone-useful without upstream design artifacts. **Consumed by:** `product-engineering`'s `frame-intent` skill — this map is the producer of the "current-state process map" input that `frame-intent` uses as a brownfield constraint. **Cross-reference:** when the process being mapped is triggered by a customer action, cross-reference the service blueprint by name (the `service-blueprint` output for the same journey).

## Output rendering

Table — When presenting several items that share the same fields, render a Markdown table. Cap at ~5 columns; beyond that, switch to a per-item detail list. Right-align numeric columns.

Diagram / flow — For relationships or flow, emit a fenced ```mermaid block (it renders in chat and artifacts). If the surface is terminal-only, fall back to an ASCII box-and-arrow sketch.

## When to invoke

Confirm all three before drafting; if any fails, resolve it first.

1. **There is a named process to map** — identify the L3 process by its trigger (what starts it), its outcome (what done looks like), and its primary actors. If the team cannot name a trigger and an outcome, elicit them inline before proceeding.

2. **The scope is internal operations** — customer-facing stage flows belong to `journey-mapping`; the screen↔service tie belongs to `service-blueprint`. This skill covers processes that span actor lanes, may have no customer-visible layer (e.g. "run the monthly close", "process supplier invoices"), or are being captured as a constraint on the solution. **This is your own org's operations, inside-out — the as-is/to-be of how *you* do it.** For *world best-practice, outside-in* — *"the best way to do X, end to end"* for any domain — use `desk-research`'s `methodology` shape instead. The two honestly share a SIPOC scope frame and a process-discovery spine; the boundary rests on source + direction (your ops vs best practice anywhere), so map here when the subject is your own process and route to the methodology shape when it is the general method.

3. **No current process map exists for this L3 process** — if one exists, you are amending it, not starting fresh. Check for an existing artifact at the path resolved in step 1 of the procedure.

## Procedure

1. **Resolve and surface the output path.** Resolve `<output_dir>` following the config-driven, two-branch elicitation procedure in `references/agentbundle-layout.md`. Resolution order: (1) repo-root `./agentbundle-layout.toml` `[design] output_dir` — repo-scope takes priority; (2) user-profile `~/.agentbundle/agentbundle-layout.toml` `[design] output_dir`; when neither resolves, two-branch elicitation runs — never a silent default: **(a) Repo branch** — suggest `docs/design/` and offer to write `output_dir` to `./agentbundle-layout.toml [design]`; **(b) Personal/vault branch** — ask for an absolute path (e.g. `~/Documents/<VaultName>/design/`) and write to `~/.agentbundle/agentbundle-layout.toml [design]`. Derive the path as `<output_dir>/processes/<slug>.md`. Resolve to a full absolute path (`~`-expand, realpath-resolve, reject `..` escapes); a repo-root-sourced `output_dir` that resolves outside the repo tree is untrusted-origin — confirm before writing. **Surface the resolved path before the first write.** Create the `processes/` directory lazily on first write.

2. **Build the SIPOC.** Before drawing any swimlane, scope the process with a SIPOC table — Suppliers, Inputs, Process (the L3 name), Outputs, Customers. This bounds the process boundary and prevents scope creep into adjacent processes. Load `references/process-mapping.md` § SIPOC scoping.

3. **Elicit or confirm the source material.** Synthesize from job aids, SOPs, and work instructions when present (document analysis — flag cross-source conflicts where the same step is described differently in different documents). When no documents are present, elicit from an SME: use a process walkthrough (default), a JAD session (multi-stakeholder or cross-department process), or a gemba walk (high-exception or hands-on process). Load `references/process-mapping.md` § Capture methods. When the elicitation is a multi-stakeholder session, run it as a **facilitated workshop** — generate silently before discussing, keep the room small, and synthesize before momentum fades; the shared method is in `../journey-mapping/references/facilitation.md`.

4. **Identify the actors and swimlanes.** Name every role, team, or system that owns at least one L4 activity in this process. Each becomes a lane in the swimlane diagram. Keep lanes to the fewest needed — merge two roles into one lane only when they never have a handoff between them.

5. **Map the as-is state.** For the current process: draw the APQC L4 activities (actions, handoffs, decision gates) across actor lanes as a mermaid flowchart with `subgraph` lanes. Mark decision gates explicitly (a diamond in BPMN vocabulary; a conditional branch in mermaid). Identify pains and waste at each handoff — the friction, delays, rework, or information gaps — and record them in the pain/waste register. Load `references/process-mapping.md` § Swimlane and APQC levels.

6. **Map the to-be state.** Design the target process: which handoffs are eliminated, automated, or resequenced; which decision gates move; which actors change. Draw the to-be swimlane. Build the as-is→to-be delta table (`| Step | As-is | To-be | Rationale |`) — this is the primary analytical output, not just the diagram.

7. **Write the artifact.** Use the template in `assets/process-flow-template.md`. Write to the resolved path with frontmatter `type: process-flow`. Confirm the written path matches the path surfaced in step 1.

8. **Name the seams.** At the end of the map, add a `## Seams` section. If the process is customer-triggered, name the `service-blueprint` artifact that covers the customer-facing layer of the same journey. Name `frame-intent` (in the `product-engineering` pack) as the consumer of this map — it uses it as a brownfield constraint input.

## Anti-patterns to refuse

- **Confusing frontstage and backstage.** This skill maps what the organisation does inside-out. What the customer experiences is `journey-mapping`'s domain. If a swimlane step is something the customer does, it belongs in the journey map, not here.

- **Descending to L5 tasks.** L5 tasks are SOP and work-instruction territory. The swimlane works at L4 activity grain — cross-functional handoffs and decision gates, not the individual keystrokes or click sequences that make up a task. Stop at the handoff, not the sub-step.

- **Reprinting APQC framework text or full BPMN XML.** Point to APQC PCF and BPMN 2.0 (OMG / ISO 19510) as standards; do not reproduce the PCF table, process categories, or BPMN element XML. The method borrows the vocabulary; the source stays authoritative.

- **Skipping the SIPOC.** A swimlane without a SIPOC has no agreed boundary. The SIPOC is what prevents the map from sprawling into adjacent processes or stopping short of the real outcome. Build it before the first lane.

- **Producing only a diagram without the delta table.** The as-is→to-be delta table is the analytical output — the reason the map earns its keep. A swimlane alone without the delta table leaves the improvement logic implicit.

- **Skipping the output-path surface step.** The resolved path is declared before the first write, every time.

- **Adding a platform/surface axis.** This skill is actor/swimlane-shaped, not device-shaped. Surface axis (`responsive-web | iOS | Android`) has no meaning here — the process actors and handoffs do not change by device. Do not add one.