---
name: okhp3/okhp3-process-quality-validation
source: https://app.decimal.ai/s/okhp3-okhp3-process-quality-validation@1/SKILL.md
source_sha256: ed531db1160e
---

# okhp3-process-quality-validation

**OverKill Hill P³** · [overkillhill.com](https://overkillhill.com) · [github.com/OKHP3](https://github.com/OKHP3)

## Purpose

Orchestrate the full validation suite across all BP-SKILL process artifacts and return a composite 0–100 quality score. The suite runs V1–V9 validation rules and returns a band classification with a binary publication gate verdict.

---

## When to use this skill

- All process artifacts exist (pir.yaml + pns.yaml minimum) and user wants a publication readiness check
- You need a single quality score before passing artifacts to `publication-and-handoff-packaging`
- User asks for a validation report or quality audit of a process documentation set

## When NOT to use this skill

- PNS has not been authored — run `process-narrative-authoring` first
- User only wants to validate a single artifact — use the artifact's own validate script directly
- Do not suppress V1–V3 errors — these are hard gates that must be resolved before publication

---

## V1–V9 Validation Rules

| Rule | Severity | Artifact | Description |
|---|---|---|---|
| V1 | error | pns.yaml | Required top-level fields present; status valid; ≥4 babok_core_concepts; all 13 section keys present |
| V2 | error | pns.yaml | Every activity has non-empty description + actor_role_id; every business rule has non-empty source |
| V3 | error | pns.yaml | Every RACI entry has exactly one Accountable and ≥1 Responsible; every activity has a RACI entry |
| V4 | warning | pns.yaml | Activity descriptions containing semicolons, >200 chars, or starting with subordinate conjunctions |
| V5 | error | pns.yaml | Every KPI must have non-empty formula and data_source |
| V6 | error | pns.yaml | Every decision_point must have ≥2 outcomes; every exception_path must have non-empty handling |
| V7 | warning | pns.yaml | controls_and_compliance is empty; activities not covered by any control |
| V8 | error | pir.yaml | PIR completeness_score ≥ 70; ready_for_narrative = true |
| V9 | warning | bpmn-beta.mmd | bpmn-beta file present; validate-bpmn-beta passes; diagram has at least one lane |

---

## Quality Score Bands

| Band | Score range | Meaning |
|---|---|---|
| **A** | 90–100 | Publication ready — all errors resolved, warnings minimal |
| **B** | 75–89 | Publication ready with minor warnings — may proceed |
| **C** | 50–74 | Below threshold — resolve errors before publication |
| **D** | 0–49 | Significant quality deficit — major rework required |

Publication gate: **Band A or B** (score ≥ 75) → `ready_for_publication: true`

---

## Validation Report Schema

`validation-report.yaml` contains:
- `process_id` — from PIR
- `validation_date`, `validated_by_role`
- `rules_run[]` — each rule: `rule_id`, `severity`, `status` (pass|fail|warn), `findings[]`
- `artifact_scores{}` — per-artifact weighted scores: `pir`, `pns`, `bpmn`
- `composite_score` — 0–100 weighted composite
- `band` — A | B | C | D
- `ready_for_publication` — true | false
- `blocking_errors[]` — rule IDs that must be resolved before publication
- `recommendations[]` — actionable items for each warning

---

## Orchestration Workflow

`scripts/run-validation-suite.mjs` executes in order:

1. Validate PIR — run `validate-pir.mjs`; record V8 pass/fail
2. Validate PNS — run `validate-pns.mjs`; record V1–V7 findings
3. Score PNS — run `score-pns-quality.mjs`; record weighted score
4. Score PIR — run `score-intake-completeness.mjs`; record completeness score
5. Validate BPMN (if present) — run `validate-bpmn-beta.mjs`; record V9 pass/fail
6. Compute composite score — weighted average across artifact scores
7. Classify band — assign A/B/C/D based on composite score
8. Set `ready_for_publication` — true only if band A or B and no V1/V2/V3/V5/V6 errors

---

## Handoff Instruction

When `ready_for_publication: true`, pass all artifacts to `publication-and-handoff-packaging`.

When `ready_for_publication: false`, present `blocking_errors[]` to the user and return to the appropriate skill to resolve each error.

---

## References

Load on demand:
- `references/validation-rules.md` — V1–V9 severity descriptions, remediation guidance, and composite scoring weights

## Scripts

- `scripts/run-validation-suite.mjs` — orchestrates V1–V9 checks and returns composite score, band, and publication gate verdict

## Assets

- `assets/fixtures/validation-report-example.yaml` — canonical validation report for purchase-approval process set

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