Immutable. This exact content is served forever at /api/v1/blob/cb4172e525c2d0d5.
---
name: okhp3-decision-model-authoring
description: Author and validate decision models from PNS decision points using DMN-aligned rule tables. Use this skill when the PNS contains three or more gateway decision points that warrant a structured decision table; when the user asks to document business rules as decision logic, build a DMN table, or make decision criteria explicit. This is a recommended extension skill triggered automatically when visual-process-modeling identifies three or more gateways. Produces a decision-model YAML and a human-readable DMN rule table.
license: MIT
homepage: https://github.com/overkillhill/mermaid-diagram-bpmn/tree/main/skills/decision-model-authoring
repository: https://github.com/overkillhill/mermaid-diagram-bpmn
metadata:
bp_skill_version: "0.3.0"
status: recommended-extension
version: "0.1.0"
author: OverKill Hill P³
project: "BP-SKILL: Business Process Agent Skill Suite"
category: process-documentation
standards_refs:
- "OMG DMN 1.4 (Decision Model and Notation)"
- "BABOK v3 §10.11 (Business Rules Analysis)"
- "BPM CBOK v4 §5.4 (Decision Modelling)"
produces: "decision-model.yaml, dmn-table.md"
consumes: "pns.yaml"
depends_on: ["process-narrative-authoring"]
tags: decision-model, DMN, business-rules, decision-table, gateways, rule-table, process-logic
triggers:
- decision table
- DMN model
- business rules table
- document decision logic
- decision model
- rule table
- three or more gateways
- make the decision criteria explicit
origin: okhp3/skillz
homepage: https://overkillhill.com
author-github: https://github.com/OKHP3
in_scope: "The named stage of the governed business-process documentation lifecycle and its stated input-output handoff."
out_of_scope: "Inventing process facts, bypassing required upstream artifacts, or publishing without authorization."
---
# okhp3-decision-model-authoring
**OverKill Hill P³** · [overkillhill.com](https://overkillhill.com) · [github.com/OKHP3](https://github.com/OKHP3)
## Purpose
Transform PNS decision_points into structured DMN-aligned decision models. Each decision point becomes a decision table with explicit input conditions, output values, and the business rule governing the routing logic.
---
## When to use this skill
- PNS has **≥3 decision_points** — this is the mandatory trigger condition
- User needs a decision table to communicate routing logic to implementers
- Business rules are complex enough that prose descriptions are insufficient
- Preparing a decision catalog as part of governance documentation
## When NOT to use this skill
- PNS has fewer than 3 decision_points — inline the logic in the PNS `decision_points[]` section
- Decision logic is trivially binary (yes/no) with no business rule — document in `business_rules[]` instead
- Do not model decisions before the PNS is validated (score ≥ 75)
---
## DMN Table Structure
Each decision table entry has:
| Field | Description |
|---|---|
| `decision_id` | Stable identifier matching `pns.decision_points[].id` |
| `decision_name` | Human-readable label |
| `activity_id` | The PNS activity where this decision occurs |
| `hit_policy` | `U` (Unique) \| `F` (First) \| `A` (Any) \| `C` (Collect) |
| `inputs[]` | Each input: `name`, `type` (string\|number\|boolean), `values[]` |
| `outputs[]` | Each output: `name`, `type`, `values[]` |
| `rules[]` | Each rule: `id`, `conditions{}`, `output{}`, `annotation` |
---
## Authoring Workflow
### Step 1 — Extract decision points
Read `pns.decision_points[]` and group by the `activity_id` where they occur.
### Step 2 — Identify inputs and outputs
For each decision:
- **Inputs** — the data values or conditions being evaluated (from `criteria`)
- **Outputs** — the possible routing outcomes (from `outcomes[].label`)
### Step 3 — Select hit policy
| Situation | Hit policy |
|---|---|
| Exactly one rule fires per input combination | U (Unique) |
| Rules are ordered; first match wins | F (First) |
| Multiple rules can fire but give the same output | A (Any) |
| Multiple rules can fire and outputs are aggregated | C (Collect) |
### Step 4 — Write rules
For each combination of input values, specify the output. Mark any unhandled combination as `FAIL` — do not silently default.
### Step 5 — Validate traceability
Every `decision_id` must match a `pns.decision_points[].id`. Every output value must match a `pns.decision_points[].outcomes[].label`.
---
## DMN Table Markdown Format
```markdown
## Decision: Approve PO Request (gw-001)
Hit policy: **U** (Unique)
| Amount | Requester Level | → Outcome |
|---|---|---|
| ≤ 1000 | any | Auto-approve |
| > 1000 | manager | Manual review |
| > 1000 | staff | Escalate to Director |
| > 10000 | any | Board approval required |
```
---
## Handoff Instruction
Pass `decision-model.yaml` and `dmn-table.md` to `publication-and-handoff-packaging` for bundle assembly.
Use `decision_id` values as gateway label annotations in the `bpmn-beta.mmd` diagram.
---
## References
Load on demand:
- `references/dmn-modeling-rules.md` — hit policy selection rules, input/output type definitions, and traceability requirements
## Scripts
- `scripts/validate-decision-model.mjs` — validates decision model structure, hit policy completeness, and PNS traceability
## Assets
- `assets/fixtures/decision-model-example.yaml` — canonical decision model for purchase-approval gateway logic
## About
Built by [Jamie Hill](https://overkillhill.com) · [OverKill Hill P³](https://overkillhill.com)
Published at [github.com/OKHP3](https://github.com/OKHP3)
Part of the [OKHP3/skillz](https://github.com/OKHP3/skillz) Agent Skill library.
MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.