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