order-management

name	order-management
description	Use when creating, updating, reviewing, or debugging orders, order status, order lifecycle, fulfillment, refunds, cancellations, state transitions, audit history, or order access control.

Order Management

Use this skill for safe order lifecycle and status management.

Rules

• Follow the project’s existing order model and status values.
• Do not invent a new state machine unless the project has no clear order flow.
• Validate every order status transition.
• Reject invalid transitions.
• Make repeated transitions to the same state safe.
• Record important status changes in audit/history when the project supports it.
• Keep order ownership and permissions server-side.
• Do not let users access or modify another user’s order.
• Keep payment, inventory, fulfillment, refund, and notification side effects consistent with existing project behavior.
• Do not trust client-provided order totals, payment state, ownership, or permissions.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing order logic, check existing patterns for:

• order statuses
• valid transitions
• checkout integration
• payment status handling
• inventory behavior
• fulfillment flow
• refund/cancellation rules
• order history/audit logs
• permissions
• test style

Implementation Checklist

• Identify the current order state.
• Identify the requested target state.
• Verify the transition is allowed.
• Verify the actor has permission.
• Make the operation idempotent where safe.
• Apply side effects only once.
• Use transactions or safe atomic updates for critical changes.
• Record audit/history if supported.
• Return errors using the existing project format.
• Add or update relevant tests.

State Transition Rules

• Keep allowed transitions explicit.
• Do not allow terminal orders to move again unless the project supports reopening.
• Common terminal states include canceled, refunded, completed, or failed.
• Payment success should not blindly skip required order states.
• Cancellation should respect payment, shipment, and fulfillment state.
• Refunds should respect payment and return rules.
• Concurrent status updates must not create inconsistent state.

Access Rules

• Customers may only act on their own orders.
• Admin/staff actions must still use valid transitions.
• System/webhook actions must be authenticated or verified.
• Organization or tenant orders must verify membership and permissions.
• Sensitive order data must not leak through errors or logs.

Side Effect Rules

Side effects may include:

• inventory reservation or release
• fulfillment creation
• shipment tracking
• refund creation
• notification sending
• audit logging

Rules:

• Run side effects according to existing project patterns.
• Avoid duplicate side effects on retries.
• Do not send duplicate notifications.
• Do not release or commit inventory twice.
• Keep payment and order state consistent.

Failure Handling

• Invalid transition: return a conflict-style error.
• Order not found or not owned: return not found or forbidden according to project pattern.
• Side effect failure: handle according to project rules; do not hide critical inconsistencies.
• Concurrent update: use locking, version checks, or transactions if available.
• Webhook duplicate: ignore safely if already processed.

Tests

Cover relevant paths:

• valid transition
• invalid transition
• repeated same transition
• unauthorized order access
• customer cancellation
• admin/status update
• payment-driven transition
• refund or return transition
• side effect runs once
• audit/history record created