---
name: okhp3/okhp3-decision-model-authoring
source: https://app.decimal.ai/s/okhp3-okhp3-decision-model-authoring@1/SKILL.md
source_sha256: eca8bd75f8a4
---

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