model-business-processes

name	model-business-processes
description	Model and validate executable business processes. Use for workflow maps, state machines, orchestration, identity gates, dry-run rules, side effects, failures, or handoffs.

Model Business Processes

Describe what the business operation means before describing how automation clicks through it. Make every side effect, identity gate, terminal state, and failure branch explicit.

Workflow

1. Set the boundary. Name the process, actor, trigger, goal, start/end states, included systems, excluded decisions, and success metric.
2. Collect evidence. Read requirements, current code, configuration, tests, logs, database states, UI behavior, and operator instructions. Mark disagreements instead of averaging them.
3. Define business semantics. Specify inputs, limit meaning, ordering, eligibility, identity, deduplication, state transitions, and what counts as processed, attempted, completed, verified, or persisted.
4. Separate layers. Keep business decisions, orchestration, platform automation, persistence, external projection, and human approval as distinct lanes.
5. Order gates before side effects. Validate authorization, page/system state, target identity, eligibility, duplicate status, and external prerequisites before any irreversible action.
6. Model the happy path and all exits. Include skip, retry, wait, manual handoff, batch stop, rollback, compensation, and partial-success behavior.
7. Define dry-run precisely. State what remains read-only, what navigation or draft mutation still occurs, what external writes are forbidden, and what evidence is produced.
8. Design observability. Give each result a reason code, evidence fields, counters, and operator-facing summary. Never report success from intent alone.
9. Map tests. Link each branch and invariant to unit, integration, installed-app, or real-system acceptance evidence.
10. Review with stakeholders. Confirm business owners understand limits, human decisions, data effects, and failure handling; confirm engineers can implement the process without guessing.

Required process invariants

• Stable identity must be established before reading or writing object-specific data.
• A state-changing action must have a fresh postcondition.
• Retries must reacquire state and remain idempotent.
• Batch counters must use one documented semantic.
• Individual failure versus batch-stop conditions must be distinct.
• Persist only evidence-backed outcomes; do not reuse stale panel/context data.
• External sync, scoring, or reporting must not corrupt the primary business transaction.
• Human approval must be explicit for actions that materially affect people or commitments.

Deliverables

Produce a concise process spec, one useful flow/state visualization, decision tables for complex gates, reason codes, data/state effects, and an acceptance matrix. Avoid duplicating code line by line.

References

• Read process-spec-template.md when creating or reviewing a process document.
• Read project-evidence.md for process patterns and failure lessons extracted from this repository.