SHIP Support Playbook

Purpose: canonical assistant playbook for SHIP operations support.

Primary audience: customer operators and first-line support.

Intent: Upload Shipments

Goal:

• Help customer upload shipment CSV and verify processing result.

Required inputs:

• Tenant/org name
• File name
• Job ID (if available)

Procedure:

1. Confirm upload path: /freight-audit.
2. Validate required CSV fields: tracking_number, carrier, ship_date.
3. If duplicate warning appears, direct user to existing job results.
4. If completed with warnings, review parse/processing diagnostics.
5. Route unresolved ingest errors to platform support with job ID and sample rows.

Intent: Review Findings and Next Action

Goal:

• Help customer move findings through the dispute workflow correctly.

Required inputs:

• Finding ID
• Current workflow state
• Desired action

Procedure:

1. Confirm current state in /ship/audit.
2. Validate allowed next actions by workflow state.
3. For credit, require confirmation fields before action.
4. If required evidence is missing, hold state and assign follow-up.
5. If state transition fails, capture API error and escalate.

Intent: Submit and Track Carrier Claims

Goal:

• Keep claims moving from DISPUTED to resolved states.

Required inputs:

• Finding ID(s)
• Carrier claim/ticket reference (externalReference) for submit/ack steps
• Deadline date (if available)

Procedure:

1. Confirm claim packet completeness.
2. Move DISPUTED -> SUBMITTED only after actual submission and required externalReference capture.
3. Move to CARRIER_REVIEW after acknowledgement with required externalReference.
4. Escalate claims within 7 days of deadline if not submitted.
5. Use CREDITED only after confirmed credit evidence.

Intent: Confirm Credit and Billing Eligibility

Goal:

• Determine whether a finding is billable recovered value.

Required inputs:

• Finding ID
• Amount
• Confirmation payload: source, reference ID, confirmed timestamp

Procedure:

1. Validate finding is in a credit-eligible state.
2. Confirm amount > 0.
3. Confirm required confirmation fields are present and valid.
4. Apply per-finding credit action.
5. Mark billable only when confirmation is complete and auditable.

Guardrails:

• Do not advise batch credit for billing-critical transitions.
• Do not infer confirmation data from partial notes.

Intent: Notification and Link Issues

Goal:

• Resolve confusion around where users should navigate from alerts.

Required inputs:

• Notification type
• Link clicked

Procedure:

1. SHIP findings/dispute links should resolve to /ship/audit.
2. Notification preference links should resolve to /notifications.
3. If link is stale, provide corrected destination and capture bug report details.

Intent: Escalation Decision

Goal:

• Decide when assistant should hand off to human operator/support.

Escalate when:

• Required evidence is unavailable for requested transition.
• Billing eligibility is ambiguous.
• Repeated API failures block workflow.
• Deadline risk is imminent.
• User requests policy exception or manual override.

Escalation payload:

• Tenant/org
• Finding/job IDs
• Current state
• Desired action
• Error/details
• Deadline/value impact