--- name: okhp3/okhp3-process-narrative-authoring source: https://app.decimal.ai/s/okhp3-okhp3-process-narrative-authoring@1/SKILL.md source_sha256: d66e3763e06e --- # okhp3-process-narrative-authoring **OverKill Hill P³** · [overkillhill.com](https://overkillhill.com) · [github.com/OKHP3](https://github.com/OKHP3) ## Purpose Transform a validated PIR and stakeholder register into a Process Narrative Specification (PNS) — the structured document that anchors process semantics for human review and downstream diagram generation. The PNS is the single source of truth between process discovery and visual modeling. It documents what the process does, who does it, how it is governed, how it is measured, and what can go wrong. --- ## When to use this skill - PIR has `completeness_score ≥ 70` and `ready_for_narrative: true` - User needs a formal process document (ISO 9001 §4.4.1, BABOK §7) - You need to produce SIPOC, RACI, or business rules as standalone artifacts - Preparing input for `visual-process-modeling` ## When NOT to use this skill - PIR has not been validated — complete `process-intake-and-scope` first - User only needs a quick diagram without governance structure — go directly to `visual-process-modeling` - Process is exploratory and roles/rules are completely unknown — return to `process-intake-and-scope` --- ## PNS Structure — 13 Required Sections ### 1. process_box (ISO 9001 §4.4.1) `trigger`, `inputs[]` (each with `name`, `source`), `outputs[]` (each with `name`, `consumer`), `criteria`, `resources`, `responsibilities`, `risks`. ### 2. activity_sequence Ordered activities. Each: `id`, `description` (single imperative per IEEE 29148), `actor_role_id`, `inputs[]`, `outputs[]`, `systems[]`, `preconditions`, `postconditions`. Minimum 3 activities for full quality score. ### 3. roles_and_raci **roles[]:** `{ role_id, role_name }`. **raci_matrix[]:** one per activity — `activity_id`, `responsible[]` (≥1), `accountable` (exactly 1), `consulted[]`, `informed[]`. ### 4. business_rules `{ id, description, source, applies_to, rationale }`. `source` is mandatory. `applies_to` references an `activity_id` or `"all"`. ### 5. decision_points `{ id, description, activity_id, criteria, outcomes[] }`. Each entry must have ≥2 outcomes. Each outcome: `{ label, next_activity }`. ### 6. exception_paths `{ id, description, trigger, handling, owner_role_id, escalation_path }`. `handling` is mandatory and non-empty. ### 7. kpis `{ id, name, formula, data_source, target, frequency }`. Both `formula` and `data_source` are mandatory. ### 8. systems_and_integrations `{ system_name, role, integration_type, activities_supported[] }`. ### 9. controls_and_compliance `{ id, type, description, standard_ref, activities_covered[], waiver }`. Empty triggers a V7 warning. ### 10. open_questions `{ id, question, owner_role_id, target_resolution_date }`. Record gaps — do not invent content. ### 11. babok_core_concepts Minimum 4 of 6 fields populated (≥20 chars each): `change`, `need`, `solution`, `stakeholders`, `value`, `context`. ### 12. revision_history `{ version, date, author_role, summary }`. Required for document change traceability. ### 13. validation (computed) `{ pns_quality_score, ready_for_publication, ready_for_bpmn_modeling }`. Populated by `scripts/score-pns-quality.mjs`. Do not author manually. --- ## V1–V7 Validation Rules | Rule | Severity | Description | |---|---|---| | V1 | error | Required top-level fields present; status valid; ≥4 babok_core_concepts; all 13 section keys present | | V2 | error | Every activity has non-empty description + actor_role_id; every business rule has non-empty source | | V3 | error | Every RACI entry has exactly one Accountable and at least one Responsible; every activity has a RACI entry | | V4 | warning | Activity descriptions containing semicolons, >200 chars, or starting with subordinate conjunctions | | V5 | error | Every KPI must have non-empty formula and data_source | | V6 | error | Every decision_point must have ≥2 outcomes; every exception_path must have non-empty handling | | V7 | warning | controls_and_compliance is empty; activities not covered by any control | Run: `node scripts/validate-pns.mjs ` --- ## Quality Score and Publication Gate Weighted 0–100. Publication threshold: **≥75**. | Section | Max pts | |---|---| | process_box | 15 | | activity_sequence | 15 | | roles_and_raci | 10 | | business_rules | 10 | | decision_points | 10 | | exception_paths | 10 | | kpis | 10 | | systems_and_integrations | 5 | | controls_and_compliance | 5 | | babok_core_concepts | 5 | | apqc_pcf_mapping | 5 | | **Total** | **100** | Run: `node scripts/score-pns-quality.mjs ` --- ## Authoring Workflow Execute in order: 1. Load PIR — read `pir.yaml` and `stakeholder-register.yaml` 2. Map inputs — PIR actors → roles, steps → activities, rules → business_rules 3. Draft process_box — trigger, inputs, outputs, criteria, responsibilities, risks 4. Expand activities — enrich each step with preconditions, postconditions, system assignments 5. Build RACI — assign R/A/C/I for each activity from PIR actor types 6. Document rules + decisions — expand business_rules with source citations; derive decision points 7. Define KPIs — at least one KPI with formula and data_source per core process objective 8. Add controls — map applicable compliance standards to activities 9. Anchor CCM — populate all 6 babok_core_concepts fields 10. Record open questions — do not invent content 11. Validate — run `scripts/validate-pns.mjs`; fix all errors before continuing 12. Score — run `scripts/score-pns-quality.mjs`; ensure score ≥75 before handoff --- ## Handoff Instruction When validation passes and score ≥ 75, pass `pns.yaml` to: - `visual-process-modeling` — for BPMN diagram generation - `sop-and-work-instruction-generation` — for SOP documents - `raci-and-governance-matrix-generation` — for standalone RACI matrix - `sipoc-generation` — for SIPOC table --- ## References Load on demand: - `references/pns-schema.md` — complete field-level documentation for all 13 sections, 9-state PNS lifecycle, and traceability rules ## Scripts - `scripts/validate-pns.mjs` — V1–V7 validation - `scripts/score-pns-quality.mjs` — weighted quality score ## Assets - `assets/fixtures/pns-example.yaml` — canonical PNS fixture for purchase-approval process ## 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.