okhp3-process-gap-exception-analysis
BP-SKILL: Business Process Agent Skill Suite · part of mermaid-diagram-bpmn · OverKill Hill P³
Purpose
Systematically identify gaps, deviations, and exception paths in a captured as-is process. The analysis distinguishes:
- Structural gaps: missing steps, undefined roles, absent inputs or outputs
- Execution gaps: steps performed inconsistently or only by specific individuals
- Exception gaps: failure paths with no documented handling
- Compliance gaps: steps missing required controls or policy references
When to use this skill
- You have an
as-is-process.yaml and want to identify improvement opportunities
- User asks where the current process fails, slows down, or creates risk
- Preparing the input for
okhp3-future-state-change-strategy
- User needs a root cause analysis of a known process failure
When NOT to use this skill
- No as-is capture exists: run
okhp3-as-is-process-capture first
- User wants to design the future state immediately: note the gap analysis is needed first, then run
okhp3-future-state-change-strategy
- Do not propose solutions here: record gaps only; solutions belong in the future-state skill
Gap Analysis Framework
scripts/analyze-gaps.mjs analyses the as-is process for the following gap types:
Type 1: Structural gaps
| Pattern |
Gap description |
Step with no actor_role_id |
Unowned activity |
| No start event or end event |
Missing process boundary |
Input with no source |
Untraced input |
Output with no consumer |
Undelivered output |
business_rules empty |
Undocumented constraints |
Type 2: Execution gaps
| Pattern |
Gap description |
capture_quality: low on step |
Poorly understood activity |
Step with notes containing "usually" or "sometimes" |
Inconsistent execution |
| Single person as sole performer across >50% of steps |
Key-person dependency |
Type 3: Exception gaps
| Pattern |
Gap description |
| Decision point with no exception path |
Unhandled failure branch |
Exception in PIR with no handling |
Undefined recovery procedure |
Exception path with owner_role_id empty |
Unowned error handling |
Type 4: Compliance gaps
| Pattern |
Gap description |
controls empty on process |
No governance controls |
Approval step with no approver role |
Missing segregation of duties |
| High-risk exception with no escalation path |
Escalation path undefined |
Severity Classification
| Severity |
Description |
critical |
Process cannot complete without this being resolved |
major |
Significant risk of nonconformity or failure |
minor |
Inconsistency or improvement opportunity |
observation |
Informational: no immediate action required |
Exception Catalog
For each exception found, record:
exception_id: stable identifierdescription: what goes wrongtrigger_condition: what causes this exceptionaffected_steps[]: which act-NNN IDs are affectedcurrent_handling: what the process does today (if anything)severity: critical | major | minor | observationrecommended_action: brief description (not a full solution)
Handoff Instruction
Pass gap-analysis.yaml and exception-catalog.yaml to okhp3-future-state-change-strategy to prioritise gaps and design the target state.
Also use exception-catalog.yaml to enrich exception_paths[] in okhp3-process-narrative-authoring.
Execution contract
Apply this contract on every run so the artifact is trustworthy and reusable:
- State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.
- Preserve stable identifiers and source traceability. When transforming an upstream artifact, retain its IDs and cite the source field or section for each derived decision.
- Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.
- Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.
- Stop and request the missing input when a boundary, approval authority, or safety-critical rule cannot be inferred. A partial artifact with clearly marked open questions is safer than a confident fabrication.
If scripts/analyze-gaps.mjs cannot run, classify gaps by hand using the four pattern tables in references/gap-analysis-framework.md, and state in the output that automated detection was not run.
References
Load on demand:
references/gap-analysis-framework.md: gap type taxonomy, severity classification, and root cause analysis templates
Scripts
scripts/analyze-gaps.mjs: detects structural, execution, exception, and compliance gaps from as-is-process.yaml
Assets
assets/fixtures/gap-analysis-example.yaml: canonical gap analysis for purchase-approval as-is process
Evaluation and release status
No evals/evals.json exists for this skill yet, and none of the five root-level evals/ categories cover gap-analysis output directly. The only current check is the maintainer-facing tests/validate-skill.test.mjs against assets/fixtures/gap-analysis-example.yaml. Evidence status: not-run for task quality and skill uplift.
Version 0.2.0 (this pass) added the compatibility declaration and the script fallback instruction; the description already stated the solutions-vs-gaps boundary, so this pass moved that sentence earlier for discovery-time visibility rather than adding a new one. Classified minor per the versioning table, not patch. No regression suite exists to run before this bump; that limitation is disclosed, not implied away.
About
Part of the BP-SKILL: Business Process Agent Skill Suite, published in overkillhill/mermaid-diagram-bpmn. MIT License.
1---2name: okhp3-process-gap-exception-analysis3description: Identify deviations, gaps, and exception paths between an as-is process capture and its intended design. Use this skill when the user wants to find where a process breaks down, where steps are missing or inconsistent, where exception handling is undefined, or where current execution differs from documented procedure. Use when they say \"what's wrong with the current process\", \"find the gaps\", \"where does this break\", or \"analyze exceptions\". Records gaps only — it does not propose solutions or redesign; for that, hand off to okhp3-future-state-change-strategy. Produces a gap analysis report and exception catalog.4license: MIT5---67# okhp3-process-gap-exception-analysis89**BP-SKILL: Business Process Agent Skill Suite** · part of [mermaid-diagram-bpmn](https://github.com/OKHP3/mermaid-diagram-bpmn) · OverKill Hill P³1011---1213## Purpose1415Systematically identify gaps, deviations, and exception paths in a captured as-is process. The analysis distinguishes:16171. **Structural gaps**: missing steps, undefined roles, absent inputs or outputs182. **Execution gaps**: steps performed inconsistently or only by specific individuals193. **Exception gaps**: failure paths with no documented handling204. **Compliance gaps**: steps missing required controls or policy references2122---2324## When to use this skill2526- You have an `as-is-process.yaml` and want to identify improvement opportunities27- User asks where the current process fails, slows down, or creates risk28- Preparing the input for `okhp3-future-state-change-strategy`29- User needs a root cause analysis of a known process failure3031## When NOT to use this skill3233- No as-is capture exists: run `okhp3-as-is-process-capture` first34- User wants to design the future state immediately: note the gap analysis is needed first, then run `okhp3-future-state-change-strategy`35- Do not propose solutions here: record gaps only; solutions belong in the future-state skill3637---3839## Gap Analysis Framework4041`scripts/analyze-gaps.mjs` analyses the as-is process for the following gap types:4243### Type 1: Structural gaps4445| Pattern | Gap description |46|---|---|47| Step with no `actor_role_id` | Unowned activity |48| No start event or end event | Missing process boundary |49| Input with no `source` | Untraced input |50| Output with no `consumer` | Undelivered output |51| `business_rules` empty | Undocumented constraints |5253### Type 2: Execution gaps5455| Pattern | Gap description |56|---|---|57| `capture_quality: low` on step | Poorly understood activity |58| Step with `notes` containing "usually" or "sometimes" | Inconsistent execution |59| Single person as sole performer across >50% of steps | Key-person dependency |6061### Type 3: Exception gaps6263| Pattern | Gap description |64|---|---|65| Decision point with no exception path | Unhandled failure branch |66| Exception in PIR with no `handling` | Undefined recovery procedure |67| Exception path with `owner_role_id` empty | Unowned error handling |6869### Type 4: Compliance gaps7071| Pattern | Gap description |72|---|---|73| `controls` empty on process | No governance controls |74| Approval step with no `approver` role | Missing segregation of duties |75| High-risk exception with no escalation path | Escalation path undefined |7677---7879## Severity Classification8081| Severity | Description |82|---|---|83| `critical` | Process cannot complete without this being resolved |84| `major` | Significant risk of nonconformity or failure |85| `minor` | Inconsistency or improvement opportunity |86| `observation` | Informational: no immediate action required |8788---8990## Exception Catalog9192For each exception found, record:93- `exception_id`: stable identifier94- `description`: what goes wrong95- `trigger_condition`: what causes this exception96- `affected_steps[]`: which `act-NNN` IDs are affected97- `current_handling`: what the process does today (if anything)98- `severity`: critical | major | minor | observation99- `recommended_action`: brief description (not a full solution)100101---102103## Handoff Instruction104105Pass `gap-analysis.yaml` and `exception-catalog.yaml` to `okhp3-future-state-change-strategy` to prioritise gaps and design the target state.106107Also use `exception-catalog.yaml` to enrich `exception_paths[]` in `okhp3-process-narrative-authoring`.108109---110111## Execution contract112113Apply this contract on every run so the artifact is trustworthy and reusable:1141151. State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.1162. Preserve stable identifiers and source traceability. When transforming an upstream artifact, retain its IDs and cite the source field or section for each derived decision.1173. Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.1184. Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.1195. Stop and request the missing input when a boundary, approval authority, or safety-critical rule cannot be inferred. A partial artifact with clearly marked open questions is safer than a confident fabrication.120121If `scripts/analyze-gaps.mjs` cannot run, classify gaps by hand using the four pattern tables in `references/gap-analysis-framework.md`, and state in the output that automated detection was not run.122123## References124125Load on demand:126- `references/gap-analysis-framework.md`: gap type taxonomy, severity classification, and root cause analysis templates127128## Scripts129130- `scripts/analyze-gaps.mjs`: detects structural, execution, exception, and compliance gaps from as-is-process.yaml131132## Assets133134- `assets/fixtures/gap-analysis-example.yaml`: canonical gap analysis for purchase-approval as-is process135136## Evaluation and release status137138No `evals/evals.json` exists for this skill yet, and none of the five root-level `evals/` categories cover gap-analysis output directly. The only current check is the maintainer-facing `tests/validate-skill.test.mjs` against `assets/fixtures/gap-analysis-example.yaml`. Evidence status: `not-run` for task quality and skill uplift.139140Version 0.2.0 (this pass) added the `compatibility` declaration and the script fallback instruction; the description already stated the solutions-vs-gaps boundary, so this pass moved that sentence earlier for discovery-time visibility rather than adding a new one. Classified minor per the versioning table, not patch. No regression suite exists to run before this bump; that limitation is disclosed, not implied away.141142---143144## About145146Part of the **BP-SKILL: Business Process Agent Skill Suite**, published in [overkillhill/mermaid-diagram-bpmn](https://github.com/OKHP3/mermaid-diagram-bpmn). MIT License.
OKHP3