okhp3-sop-work-instructions

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Purpose

Generate a Standard Operating Procedure (SOP) and role-specific work instructions from a validated PNS. The SOP is the human-readable manifestation of the process — designed for practitioners who execute the process, not analysts who model it.

When to use this skill

• PNS quality score ≥ 75 and ready_for_publication: true
• User needs a document that practitioners can follow step-by-step
• Organisation requires ISO 9001 §4.4.2 documented information
• User wants role-specific work instructions for each lane in the RACI

When NOT to use this skill

• PNS does not exist or is below quality threshold — complete process-narrative-authoring first
• User only wants the BPMN diagram — use visual-process-modeling directly
• Do not generate SOPs from incomplete or unvalidated process descriptions

SOP Structure (ISO 9001 §7.5)

1. Header

• Document ID, version, date, owner role
• Process name and scope
• Effective date and review date
• Approved by (role, not person name)

2. Purpose and Scope

One paragraph each:

• Purpose — what this SOP achieves and why it exists (from pns.process_box.trigger and babok_core_concepts.need)
• Scope — what is included and explicitly excluded (from pns.process_box inputs/outputs and scope-statement.md)

3. Definitions

Terms and acronyms used in the SOP. Include all role names, system names, and business rule terms.

4. Responsibilities

RACI summary table: one row per activity, columns R/A/C/I. Derived from pns.roles_and_raci.raci_matrix[].

5. Procedure Steps

Sequential numbered steps derived from pns.activity_sequence.activities[]. Each step:

• Step number and title (from activity.description)
• Actor (from activity.actor_role_id)
• Action — one imperative statement per IEEE 29148
• Input — what the actor needs before starting
• Output — what the actor produces
• System — which system or tool is used
• Decision note (if activity has a matching decision_points[] entry)
• Exception note (if activity has a matching exception_paths[] entry)

6. Exception Handling

Table of exceptions: exception_id, trigger condition, handling procedure, escalation path, owner role. Derived from pns.exception_paths[].

7. Business Rules

List of governing rules. Each: rule ID, description, source citation. Derived from pns.business_rules[].

8. Related Documents

References to PIR, PNS, BPMN diagram, RACI matrix, SIPOC table.

9. Revision History

Table of document changes. From pns.revision_history[].

Work Instructions (Role-Specific)

When work-instructions.md is requested, generate one section per role:

• Header: role name, activities they own
• Numbered steps scoped to that role only
• Decision points where their judgement is required
• Exception paths they own

Generation Workflow

scripts/generate-sop.mjs reads pns.yaml and:

1. Extracts header metadata from PNS frontmatter
2. Generates Purpose from babok_core_concepts.need + process_box.trigger
3. Generates Scope from process_box.inputs[] + process_box.outputs[]
4. Builds definitions from all role_name, system_name, and business_rules[].description terms
5. Renders RACI table from raci_matrix[]
6. Renders procedure steps from activity_sequence[] with decision and exception notes
7. Renders exception table from exception_paths[]
8. Renders business rules list from business_rules[]
9. Generates revision history from revision_history[]

Handoff Instruction

Pass sop.md and work-instructions.md to publication-and-handoff-packaging for bundle assembly.

References

Load on demand:

• references/sop-structure-rules.md — ISO 9001 §4.4.2 and §7.5 requirements, SOP heading conventions, and work instruction generation rules

Scripts

• scripts/generate-sop.mjs — generates sop.md and work-instructions.md from PNS YAML

Assets

• assets/fixtures/sop-example.yaml — canonical SOP metadata fixture for purchase-approval process

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.