Approval workflow

Problem Context

• A request has already been drafted or submitted and a policy, workflow, governance, financial, release, access, procurement, content, or compliance rule requires human or external approval.
• The approval route may be one approver, any one of several approvers, every assigned approver, a threshold, a percentage, a named sequence, a group, a code owner, a manager chain, or a custom external gate.
• Approvers need enough context to make a decision without leaking unnecessary data or acting on stale versions.
• Requesters need status, ownership, due date, comments, revise or withdraw paths, and final consequences.
• The product must preserve audit evidence for approve, reject, request changes, delegate, reassign, cancel, timeout, revoke, bypass, and resubmit events.

Selection Rules

• Choose approval workflow when the core job is routing a submitted request through one or more authorized decisions before work can continue.
• Use review before submit when the requester is still checking their own inputs before the request enters an approval route.
• Use permission recovery when the user is blocked by missing access and is requesting authorization for themselves.
• Use invite user when another person is being invited into a workspace, organization, team, repository, channel, or shared resource.
• Use confirmation dialog for an immediate local confirmation, not for long-running approval routes with status, approvers, comments, and audit trail.
• Use activity log for the historical trail of approval events, not as the primary decision interface.
• Show whether the rule is everyone must approve, first to respond, threshold, percentage, sequential, code-owner, group, or custom policy gate.
• Block or clearly flag self-review when policy requires a separate approver.
• Expose rejection, requested changes, timeout, cancellation, delegation, bypass, and resubmission as specific states with different next actions.
• Keep approver notifications deep-linked to the canonical approval record so decisions are made against current request context.

Required States

• Draft or submit-ready request handoff state
• Submitted and awaiting route calculation state
• Pending approver state with current owner or group
• Approver decision state with Approve, Reject, and comment controls
• Sequential next-approver state
• Parallel approval progress state
• Requested changes state
• Rejected state with reason and revise or close path
• Approved state with downstream action or release
• Delegated or reassigned approver state
• Due soon, expired, or timed-out state
• Canceled or withdrawn state
• Bypassed or admin override state with audit reason

Interaction Contract

• Submitting creates a durable approval record with requester, target, requested action, version, approver rule, due date, and route state.
• Approver controls are available only to eligible approvers and must show the current request version and required context before decision.
• Approve, reject, request changes, delegate, reassign, withdraw, cancel, revoke approval, bypass, and resubmit actions update the same record and timeline.
• Sequential routes move to the next required approver only after the current approver responds.
• Parallel routes compute completion according to the configured rule, such as everyone approves, first response, threshold, percentage, or any rejection stops.
• Rejected and change-requested outcomes preserve requester inputs and comments so revisions do not start from an empty request.
• Notifications and email actions must verify the record is still current before accepting a decision.
• Final approval triggers the downstream operation only after all required gates pass; final rejection, expiry, or cancellation blocks it.
• The audit trail records actor, role, decision, comment, timestamp, route rule, delegation, bypass, and version context.

Implementation Checklist

• Model approval record, request version, requester, target object, requested action, approval rule, approver eligibility, due date, decision states, comments, attachments, and audit events separately from the drafted request form.
• Define route semantics for one approver, first response, everyone must approve, threshold, percentage, sequential chain, code owner, manager chain, group, manual approver, custom policy, timeout, and bypass.
• Design requester, approver, admin, and observer views with the same canonical state but role-appropriate actions.
• Show enough request detail, risk, attachment, diff, cost, access, release, or publication impact for a decision, and hide restricted details from ineligible viewers.
• Require rejection and change-request comments when the requester needs an actionable next step.
• Preserve request data, comments, attachments, route history, and return context through revision, resubmission, browser Back, reload, and notification deep links.
• Prevent stale decisions by checking version, eligibility, current status, and route membership before accepting approval from email, mobile, or background notifications.
• Implement escalation, due date, reminder, delegate, reassign, withdraw, cancel, and admin bypass paths with audit reasons.
• Test everyone-approves, first-to-respond, sequential, threshold, self-review block, duplicate decision, late decision after timeout, rejection with reason, requested changes, delegation, cancellation, bypass, mobile decision controls, keyboard navigation, and screen reader status updates.

Common Generated-UI Mistakes

• Showing a generic pending message without the approver, gate, rule, or due date.
• Treating the first approval as final when the rule requires more approvers.
• Letting requesters approve their own protected work without an explicit bypass rule.
• Collecting Approve or Reject without showing the current request version or impact.
• Dropping requester inputs after rejection or requested changes.
• Using a notification as the only approval surface and losing the canonical record.
• Conflating approval workflow with review before submit, review queue, assignment, or activity log.
• Failing to audit delegation, reassignment, cancellation, timeout, revocation, and bypass.

Critique Questions

• Who requested the approval, what object or action is being approved, and what version is the approver deciding on?
• Which rule applies: one approver, everyone, first response, threshold, percentage, sequence, group, manager, code owner, or custom policy?
• Who can approve, who is blocked from self-review, and how are unavailable approvers handled?
• What happens after approval, rejection, requested changes, timeout, cancellation, or bypass?
• Can the requester revise without losing context, and can approvers see what changed since the last route?
• Does the audit trail explain every decision, comment, route change, delegation, and override?