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:

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

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.