okhp3-decision-model-authoring

OverKill Hill P³ · overkillhill.com · 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 · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.