Ship Playbook Index.v1

{
  "version": "1.0.0",
  "intents": [
    {
      "id": "ship.upload_shipments",
      "title": "Upload Shipments",
      "description": "Guide user through SHIP upload, duplicate handling, and ingest diagnostics."
    },
    {
      "id": "ship.review_findings",
      "title": "Review Findings",
      "description": "Help user choose valid workflow actions from current finding state."
    },
    {
      "id": "ship.submit_claims",
      "title": "Submit and Track Claims",
      "description": "Drive disputes from DISPUTED to resolution with deadline-aware escalation."
    },
    {
      "id": "ship.confirm_credit",
      "title": "Confirm Credit",
      "description": "Enforce per-finding confirmation contract for CREDITED transitions."
    },
    {
      "id": "ship.notifications_links",
      "title": "Notification and Link Issues",
      "description": "Resolve stale or incorrect SHIP and notification navigation links."
    },
    {
      "id": "ship.escalation",
      "title": "Escalation Decision",
      "description": "Determine when to hand off to human operations/support."
    }
  ],
  "source_docs": [
    {
      "path": "docs/runbooks/ship-claims-operations.md",
      "sections": [
        "Intake Cadence",
        "Workflow States and Operator Actions",
        "Evidence Requirements by Transition",
        "Escalation Matrix",
        "Failure Handling Playbooks",
        "What Support Asks First (Checklist)"
      ]
    },
    {
      "path": "docs/runbooks/ship-billing-controls.md",
      "sections": [
        "Billing Gate Policy",
        "Pre-Invoice Sampling Checklist",
        "Audit Trail Retention Expectations",
        "Exception Handling and Approval Path",
        "Controls for Batch and Automation Paths"
      ]
    },
    {
      "path": "docs/chatbot/ship-support-playbook.md",
      "sections": [
        "Intent: Upload Shipments",
        "Intent: Review Findings and Next Action",
        "Intent: Submit and Track Carrier Claims",
        "Intent: Confirm Credit and Billing Eligibility",
        "Intent: Notification and Link Issues",
        "Intent: Escalation Decision"
      ]
    },
    {
      "path": "docs/chatbot/ship-support-faq.md",
      "sections": [
        "How do I upload weekly shipment files?",
        "When can I mark a finding as credited?",
        "Can I credit findings in batch?",
        "What does billable recovered value mean?",
        "When should I escalate to human support?"
      ]
    }
  ],
  "required_inputs": [
    {
      "intent": "ship.upload_shipments",
      "fields": ["tenant", "file_name", "job_id"]
    },
    {
      "intent": "ship.review_findings",
      "fields": ["finding_id", "workflow_status", "requested_action"]
    },
    {
      "intent": "ship.submit_claims",
      "fields": [
        "finding_id",
        "external_reference",
        "carrier_acknowledgement_reference",
        "dispute_deadline"
      ]
    },
    {
      "intent": "ship.confirm_credit",
      "fields": [
        "finding_id",
        "amount",
        "confirmation.source",
        "confirmation.reference_id",
        "confirmation.confirmed_at"
      ]
    },
    {
      "intent": "ship.notifications_links",
      "fields": ["notification_type", "current_link"]
    },
    {
      "intent": "ship.escalation",
      "fields": ["tenant", "finding_or_job_id", "error_or_blocker", "deadline_impact"]
    }
  ],
  "decision_rules": [
    {
      "id": "rule.credit.requires_confirmation",
      "if": "intent == ship.confirm_credit",
      "then": "Reject incomplete confirmation payload; request missing fields before action."
    },
    {
      "id": "rule.billing.confirmed_credit_only",
      "if": "question involves billable recovered value",
      "then": "Treat only CREDITED findings with complete confirmation evidence as billable."
    },
    {
      "id": "rule.batch_credit.disallow",
      "if": "user asks to batch credit findings",
      "then": "Direct to per-finding credit flow in /ship/audit."
    },
    {
      "id": "rule.notification.paths",
      "if": "user asks where to manage disputes or preferences",
      "then": "Use /ship/audit for SHIP findings and /notifications for preferences."
    }
  ],
  "escalation_rules": [
    {
      "id": "esc.missing_evidence",
      "condition": "Required evidence for requested transition is unavailable.",
      "action": "Escalate to human operator with finding ID and missing evidence list."
    },
    {
      "id": "esc.billing_ambiguity",
      "condition": "Billing eligibility cannot be determined from available records.",
      "action": "Escalate to billing owner before invoice issuance."
    },
    {
      "id": "esc.deadline_risk",
      "condition": "Claim deadline is <= 7 days and state is not SUBMITTED.",
      "action": "Escalate to operations lead with deadline and value-at-risk."
    },
    {
      "id": "esc.repeated_failures",
      "condition": "Repeated API/UI action failures block workflow progression.",
      "action": "Escalate to platform support with endpoint, payload, and error output."
    }
  ]
}