okhp3-process-measures-controls
BP-SKILL: Business Process Agent Skill Suite · part of mermaid-diagram-bpmn · OverKill Hill P³
Purpose
Define measurable process KPIs and structured compliance controls, enriching the PNS with the governance layer required for ISO 9001 §9.1 monitoring and COSO-aligned internal controls.
When to use this skill
- PNS quality score ≥ 75 and user needs additional governance structure
- User needs to map process activities to a control framework
- Preparing process documentation for audit or certification
- PNS
kpis[] or controls_and_compliance[] sections are sparse and need enrichment
When NOT to use this skill
- PNS does not exist or is below quality threshold: complete
okhp3-process-narrative-authoring first
- User only needs basic KPIs: use the KPI authoring in
okhp3-process-narrative-authoring directly
- Do not invent performance targets without user confirmation: record as
target: TBD with an open question
Measures Register Design
KPI categories
| Category |
Examples |
| Cycle time |
Average time from trigger to completion |
| Quality |
Error rate, rework rate, exception rate |
| Volume |
Transactions per period |
| Compliance |
% of steps completed with required controls |
| Cost |
Cost per transaction |
| Customer |
Satisfaction score, response time |
KPI schema
Each KPI in measures-register.yaml:
kpi_id: stable identifier (kpi-001, kpi-002, …)name: human-readable labelcategory: from taxonomy aboveformula: calculation description (mandatory)data_source: system or record that provides the data (mandatory)target: numeric target or "TBD"frequency: measurement frequency (daily | weekly | monthly | quarterly)owner_role_id: from PNS roles_and_raci.roles[]activities_measured[]: list of act-NNN IDs this KPI covers
Controls Register Design
Control types (COSO-aligned)
| Type |
Description |
preventive |
Stops an error from occurring |
detective |
Identifies an error after it occurs |
corrective |
Fixes an error once detected |
directive |
Guides behaviour through policy or procedure |
Control schema
Each control in controls-register.yaml:
control_id: stable identifier (ctrl-001, ctrl-002, …)type: from COSO taxonomy abovedescription: what the control doesstandard_ref: the policy, regulation, or framework referenceactivities_covered[]: list of act-NNN IDs this control applies tofrequency: when the control is appliedevidence_required: what evidence demonstrates the control operatedowner_role_id: from PNS roles_and_raci.roles[]
Handoff Instruction
Merge measures-register.yaml KPI entries back into pns.yaml kpis[] section. Merge controls-register.yaml entries into pns.yaml controls_and_compliance[]. Re-run okhp3-process-validation-scoring to verify score improves.
Execution contract
Apply this contract on every run so the artifact is trustworthy and reusable:
- State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.
- Preserve stable identifiers and source traceability. When transforming an upstream artifact, retain its IDs and cite the source field or section for each derived decision.
- Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.
- Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.
- Stop and request the missing input when a boundary, approval authority, or safety-critical rule cannot be inferred. A partial artifact with clearly marked open questions is safer than a confident fabrication.
If scripts/generate-measures-register.mjs cannot run, scaffold both registers by hand using references/kpi-design-rules.md, and state in the output that automated generation was not run.
References
Load on demand:
references/kpi-design-rules.md: KPI category taxonomy, formula construction rules, data source requirements, and COSO control type definitions
Scripts
scripts/generate-measures-register.mjs: scaffolds measures and controls registers from PNS kpis and controls sections
Assets
assets/fixtures/measures-register-example.yaml: canonical measures and controls for purchase-approval process
Evaluation and release status
No evals/evals.json exists for this skill yet. Its output feeds back into the PNS, so it is indirectly touched by evals/control-coverage/ once that category's stale validator_module path is fixed (see okhp3-process-narrative-authoring's Evaluation section), but nothing evaluates measures-register.yaml or controls-register.yaml directly. The only current check is the maintainer-facing tests/validate-skill.test.mjs against assets/fixtures/measures-register-example.yaml. Evidence status: not-run for task quality and skill uplift.
Version 0.2.0 (this pass) added the compatibility declaration, the script fallback instruction, and a sharper discovery-time boundary against the PNS's own inline kpis[] authoring. Classified minor per the versioning table, not patch. No regression suite exists to run before this bump; that limitation is disclosed, not implied away.
About
Part of the BP-SKILL: Business Process Agent Skill Suite, published in overkillhill/mermaid-diagram-bpmn. MIT License.
1---2name: okhp3-process-measures-controls3description: Define process performance measures, KPIs, and compliance controls for a validated PNS. Use this skill when the user needs to add measurability and governance to a documented process; when they ask to define KPIs, set performance targets, add compliance controls, or map the process to a control framework. This is a recommended extension skill — use after okhp3-process-narrative-authoring when governance and measurement rigour beyond the PNS's own kpis section is required. Produces a measures register and a controls register.4license: MIT5---67# okhp3-process-measures-controls89**BP-SKILL: Business Process Agent Skill Suite** · part of [mermaid-diagram-bpmn](https://github.com/OKHP3/mermaid-diagram-bpmn) · OverKill Hill P³1011---1213## Purpose1415Define measurable process KPIs and structured compliance controls, enriching the PNS with the governance layer required for ISO 9001 §9.1 monitoring and COSO-aligned internal controls.1617---1819## When to use this skill2021- PNS quality score ≥ 75 and user needs additional governance structure22- User needs to map process activities to a control framework23- Preparing process documentation for audit or certification24- PNS `kpis[]` or `controls_and_compliance[]` sections are sparse and need enrichment2526## When NOT to use this skill2728- PNS does not exist or is below quality threshold: complete `okhp3-process-narrative-authoring` first29- User only needs basic KPIs: use the KPI authoring in `okhp3-process-narrative-authoring` directly30- Do not invent performance targets without user confirmation: record as `target: TBD` with an open question3132---3334## Measures Register Design3536### KPI categories3738| Category | Examples |39|---|---|40| Cycle time | Average time from trigger to completion |41| Quality | Error rate, rework rate, exception rate |42| Volume | Transactions per period |43| Compliance | % of steps completed with required controls |44| Cost | Cost per transaction |45| Customer | Satisfaction score, response time |4647### KPI schema4849Each KPI in `measures-register.yaml`:50- `kpi_id`: stable identifier (kpi-001, kpi-002, …)51- `name`: human-readable label52- `category`: from taxonomy above53- `formula`: calculation description (mandatory)54- `data_source`: system or record that provides the data (mandatory)55- `target`: numeric target or `"TBD"`56- `frequency`: measurement frequency (daily | weekly | monthly | quarterly)57- `owner_role_id`: from PNS `roles_and_raci.roles[]`58- `activities_measured[]`: list of `act-NNN` IDs this KPI covers5960---6162## Controls Register Design6364### Control types (COSO-aligned)6566| Type | Description |67|---|---|68| `preventive` | Stops an error from occurring |69| `detective` | Identifies an error after it occurs |70| `corrective` | Fixes an error once detected |71| `directive` | Guides behaviour through policy or procedure |7273### Control schema7475Each control in `controls-register.yaml`:76- `control_id`: stable identifier (ctrl-001, ctrl-002, …)77- `type`: from COSO taxonomy above78- `description`: what the control does79- `standard_ref`: the policy, regulation, or framework reference80- `activities_covered[]`: list of `act-NNN` IDs this control applies to81- `frequency`: when the control is applied82- `evidence_required`: what evidence demonstrates the control operated83- `owner_role_id`: from PNS `roles_and_raci.roles[]`8485---8687## Handoff Instruction8889Merge `measures-register.yaml` KPI entries back into `pns.yaml` `kpis[]` section. Merge `controls-register.yaml` entries into `pns.yaml` `controls_and_compliance[]`. Re-run `okhp3-process-validation-scoring` to verify score improves.9091---9293## Execution contract9495Apply this contract on every run so the artifact is trustworthy and reusable:96971. State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.982. Preserve stable identifiers and source traceability. When transforming an upstream artifact, retain its IDs and cite the source field or section for each derived decision.993. Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.1004. Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.1015. Stop and request the missing input when a boundary, approval authority, or safety-critical rule cannot be inferred. A partial artifact with clearly marked open questions is safer than a confident fabrication.102103If `scripts/generate-measures-register.mjs` cannot run, scaffold both registers by hand using `references/kpi-design-rules.md`, and state in the output that automated generation was not run.104105## References106107Load on demand:108- `references/kpi-design-rules.md`: KPI category taxonomy, formula construction rules, data source requirements, and COSO control type definitions109110## Scripts111112- `scripts/generate-measures-register.mjs`: scaffolds measures and controls registers from PNS kpis and controls sections113114## Assets115116- `assets/fixtures/measures-register-example.yaml`: canonical measures and controls for purchase-approval process117118## Evaluation and release status119120No `evals/evals.json` exists for this skill yet. Its output feeds back into the PNS, so it is indirectly touched by `evals/control-coverage/` once that category's stale `validator_module` path is fixed (see `okhp3-process-narrative-authoring`'s Evaluation section), but nothing evaluates `measures-register.yaml` or `controls-register.yaml` directly. The only current check is the maintainer-facing `tests/validate-skill.test.mjs` against `assets/fixtures/measures-register-example.yaml`. Evidence status: `not-run` for task quality and skill uplift.121122Version 0.2.0 (this pass) added the `compatibility` declaration, the script fallback instruction, and a sharper discovery-time boundary against the PNS's own inline `kpis[]` authoring. Classified minor per the versioning table, not patch. No regression suite exists to run before this bump; that limitation is disclosed, not implied away.123124---125126## About127128Part of the **BP-SKILL: Business Process Agent Skill Suite**, published in [overkillhill/mermaid-diagram-bpmn](https://github.com/OKHP3/mermaid-diagram-bpmn). MIT License.
OKHP3