| 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
