process-mapping

name

process-mapping

description

Use when a team needs to understand, document, or improve how an internal business operation works — mapping an APQC L3 process end-to-end as a swimlane flow with as-is and to-be states, a SIPOC scoping table, and a pain/waste register. Triggers on "map our internal process", "document this business process", "what does our current process look like", "as-is to-be process", "process improvement", "how does this workflow actually work", "swimlane diagram for this process", "map the claims process", "map the order fulfilment flow". This is the inside-out operations sibling of `journey-mapping`. Do NOT use to map what a customer experiences (use `journey-mapping`), to blueprint how screens tie to backing services (use `service-blueprint`), or to sequence screen transitions (use `user-flow`). Does NOT carry a platform/surface axis — it is actor/swimlane-shaped, not device-shaped.

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).

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.