Okhp3 Process Intake And Scope

okhp3-process-intake-and-scope

BP-SKILL: Business Process Agent Skill Suite · part of mermaid-diagram-bpmn · OverKill Hill P³

Purpose

This skill guides structured process intake and scope definition using BABOK v3-aligned elicitation techniques. It produces:

1. Process Intake Record (PIR): structured YAML with trigger, actors, inputs, outputs, steps, exceptions, business rules, systems, and controls
2. Scope Statement: concise prose defining process boundaries, exclusions, and success criteria

The PIR is the foundational input consumed by every downstream skill in the BP-SKILL suite.

When to use this skill

• User wants to document a process they describe in natural language, bullet points, or prose
• User says "help me scope this," "let's map this process," or "define the boundaries"
• You need a structured PIR before calling okhp3-stakeholder-and-role-mapping or okhp3-process-narrative-authoring
• User wants to capture business rules, exception paths, or system touchpoints for a workflow

When NOT to use this skill

• A validated PIR with ready_for_narrative: true already exists: proceed to okhp3-process-narrative-authoring
• A PIR exists but has gaps to fill through targeted follow-up: use okhp3-elicitation-interviews instead of restarting intake
• User wants a diagram without prior discovery: use okhp3-visual-process-modeling with their description
• Do not invent process details the user has not provided: record gaps as open_questions

Intake Workflow

Execute the following stages in order. Conduct a natural conversation: do not present these as a checklist. Load references/pir-schema.md for full field reference.

Stage 0: Orientation

Ask: "Before we start, can you give me one sentence: what does this process produce or accomplish?"

Record as process_name. If vague, probe: "Who benefits when this process runs correctly? What do they get?"

Stage 1: Trigger

Ask: "What causes this process to start: a person doing something, a scheduled date, an incoming message, or a system event?"

Classify trigger.event_type:

• Person acts → manual
• Date/frequency → scheduled
• Message/request/email → message
• System condition → system

Stage 2: Actors

Ask: "Who is involved: who does work, makes decisions, or needs to know the outcome?"

Classify each actor: initiator | performer | approver | reviewer | notified | system.

Minimum: at least one initiator and one performer or approver.

Stage 3: Inputs and Outputs

Ask: "What does this process need to begin?" and "What does it produce when complete?"

Capture name, source/consumer, and format for each.

Stage 4: Scope Boundaries

Ask: "What is explicitly outside the scope of this process? Where does it hand off?"

Record out-of-scope items in scope_statement.exclusions.

Stage 5: Steps (Happy Path)

Ask: "Walk me through what happens, step by step."

After the happy path, probe for: notification steps, logging steps, waiting/pause steps.

Stage 6: Business Rules and Decision Points

For each decision: "Who makes this? What are the outcomes? Is there a policy or rule that governs it?"

Classify rule source: policy | regulation | contract | practice.

Stage 7: Exception Paths

Ask: "What can go wrong? What happens when it does?"

Stage 8: Systems and Controls

Ask: "Which systems or tools are used?" and "Are there any checkpoints, approvals, or audits built in?"

Stage 9: Open Questions

Record all unresolved gaps as open_questions: do not assume answers.

PIR Completeness Scoring

scripts/score-intake-completeness.mjs returns a 0–100 weighted score.

Handoff threshold: score ≥ 70 → ready_for_narrative: true

Output Format

1. Produce pir.yaml using assets/fixtures/intake-purchase-approval.yaml as the schema reference
2. Run scripts/score-intake-completeness.mjs to compute completeness_score and ready_for_narrative
3. Produce scope-statement.md summarising process name, trigger, boundary, exclusions, and success criteria

Handoff Instruction

When ready_for_narrative: true:

• Pass pir.yaml to okhp3-stakeholder-and-role-mapping to derive the stakeholder register
• Then pass pir.yaml + stakeholder-register.yaml to okhp3-process-narrative-authoring

When ready_for_narrative: false, report missing sections and ask targeted follow-up questions, or hand off to okhp3-elicitation-interviews for a structured question plan.

Execution contract

Apply this contract on every run so the artifact is trustworthy and reusable:

1. State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.
2. 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.
3. Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.
4. Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.
5. 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-pir.mjs, scripts/validate-pir.mjs, or scripts/score-intake-completeness.mjs cannot run, draft and hand-score the PIR against references/pir-schema.md's field table and scoring weights, and state in the output that automated generation, validation, or scoring was not run.

References

Load on demand:

• references/pir-schema.md: complete field reference for PIR YAML

Scripts

• scripts/generate-pir.mjs: scaffolds a blank PIR YAML from a brief process description
• scripts/validate-pir.mjs: schema completeness and type validation
• scripts/score-intake-completeness.mjs: 0–100 weighted completeness score

Assets

• assets/fixtures/intake-purchase-approval.yaml: canonical PIR fixture (purchase approval)

Evaluation and release status

This is the one skill in the suite with a working, verified root-level eval category: evals/discovery-quality/ (weight 20, V8 gate) exercises validatePir() against three fixtures (good-intake-purchase-approval.yaml: pass; poor-intake-missing-trigger.yaml: fail; poor-intake-missing-scope.yaml: fail) — except its manifest.json currently points validator_module at skills/okhp3-process-discovery/scripts/validate-pir.mjs, a path that does not exist in this repository. The real module is skills/okhp3-process-intake-and-scope/scripts/validate-pir.mjs. Verified by static path inspection in this session, not by a live run; node scripts/run-eval-suite.mjs would currently fail to load this category with Module not found. Fixing the validator_module string in evals/discovery-quality/manifest.json is outside this task's scope (repo-root evals/, not skills/*/SKILL.md) but is the single highest-leverage follow-up for this skill's evidence base — flagged here rather than silently left implied as working.

No dedicated evals/evals.json exists in this skill's own package. Evidence status: not-run (live) / analytical (the path-break above, verified statically) for task quality and skill uplift.

Version 0.2.0 (this pass) added the compatibility declaration, per-script fallback instructions, and a discovery-time boundary clarifying this is the first-pass intake skill (not the gap-filling one — see okhp3-elicitation-interviews). Classified minor per the versioning table, not patch. No live regression run backs 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.