| 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
- Set the boundary. Name the process, actor, trigger, goal, start/end states, included systems, excluded decisions, and success metric.
- Collect evidence. Read requirements, current code, configuration, tests, logs, database states, UI behavior, and operator instructions. Mark disagreements instead of averaging them.
- Define business semantics. Specify inputs,
limit meaning, ordering, eligibility, identity, deduplication, state transitions, and what counts as processed, attempted, completed, verified, or persisted.
- Separate layers. Keep business decisions, orchestration, platform automation, persistence, external projection, and human approval as distinct lanes.
- Order gates before side effects. Validate authorization, page/system state, target identity, eligibility, duplicate status, and external prerequisites before any irreversible action.
- Model the happy path and all exits. Include skip, retry, wait, manual handoff, batch stop, rollback, compensation, and partial-success behavior.
- 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.
- Design observability. Give each result a reason code, evidence fields, counters, and operator-facing summary. Never report success from intent alone.
- Map tests. Link each branch and invariant to unit, integration, installed-app, or real-system acceptance evidence.
- 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
