Retail Supply Chain Pulse

Overview

Delivers a prioritized supply chain exception digest each morning. Classifies inbound delays, stockout risks, demand spikes, and carrier SLA breaches by severity, estimates revenue impact per exception, diagnoses root causes, and recommends resolutions with ownership assignments. Works with any WMS/TMS/OMS connector, spreadsheet, or CSV export.

Workflow

<Definition - Data Source Cascade> Try in order, stop at first success:

1. Amazon Quick Dataset Q&A (if a QuickSight dataset is configured): ask questions directly in natural language against the full dataset with automatic SQL generation and security enforcement.
2. WMS/TMS/OMS MCP connector detected (any SQL-compatible or logistics API connector): query for order/shipment/inventory data.
3. Data source input provided as file path (.csv, .xlsx): parse with run_python.
4. Spreadsheet connector available (Google Sheets, OneDrive): search for "exceptions", "shipments", or "inventory" files.
5. Nothing available: ask user to upload exception logs or provide a file. </Definition - Data Source Cascade>

<Definition - Exception Categories>

• Inbound Delay: expected_date passed without delivery (carrier or supplier caused).
• Stockout Risk: inventory below reorder point with no inbound within lead time.
• Demand Spike: actual demand exceeds forecast by more than 30% for a SKU/location.
• Carrier SLA Breach: carrier on-time rate below contracted threshold.
• Supplier Fill Rate Drop: supplier delivering less than 90% of ordered quantity. </Definition - Exception Categories>

<Definition - Severity Score> A composite 1-10 score per exception:

• Revenue impact weight: 40% (higher $ = higher score)
• Customer visibility weight: 25% (customer-facing stockout scores higher than backroom issue)
• Time urgency weight: 20% (hours until impact)
• Breadth weight: 15% (number of locations/SKUs affected) Score 8-10 = Critical, 5-7 = Warning, 1-4 = Watch. </Definition - Severity Score>

<Definition - Resolution> A recommended action for each exception including:

• Specific action to take (e.g., "Expedite PO #4521 via air freight")
• Ownership role (e.g., "Transportation Manager")
• Deadline based on severity: Critical = 4 hours, Warning = 24 hours, Watch = 48 hours
• Estimated cost of action vs cost of inaction </Definition - Resolution>

<Workflow - Setup description="First-run configuration and data source detection." tools=[run_python, file_read] triggers=["first time", "configure supply chain", "setup pulse"]

[Decide] Check if {{config_directory}}/supply-chain-pulse-config.json exists:

• EXISTS: Load saved configuration (data source, column mappings, severity threshold, regions). Proceed to Generate Pulse workflow.
• DOES NOT EXIST: Continue with setup below. Validate: File existence determined. If fails: Assume first run.

[Ask user] "This is your first Supply Chain Pulse. I need to understand your data setup:

1. Where does your order/shipment data live? (file path, or data warehouse connection)
2. Do you have inventory level data? (yes/no, where)
3. Which regions or DCs should I monitor? (or 'all')
4. What severity threshold do you want? (1-10, where 4 is recommended to start)" Validate: User responds with at least a data source. If fails: Offer to run a demo pulse with synthetic data so the user can preview the output.

[Decide] Detect data source type per <Definition - Data Source Cascade>:

• MCP connector detected: probe with a lightweight query to verify connectivity.
• File path provided: verify file exists with file_read.
• Nothing found: offer to generate a sample template CSV. Validate: At least one data source is accessible. If fails: [Ask user] "Could not access that source. Upload a CSV or Excel file with columns: order_id, status, expected_date, actual_date, carrier, sku, quantity, location."

[Agent] Map column names to expected schema: order_id, status, expected_date, actual_date, carrier, sku, quantity, location, supplier, fill_rate. If names differ, infer from headers and confirm ambiguous mappings. Validate: At least order_id, status, expected_date, and actual_date are mapped. If fails: [Ask user] to clarify which columns represent order identifiers, dates, and statuses.

[Agent] Save configuration to {{config_directory}}/supply-chain-pulse-config.json. Validate: Config file written. If fails: Present config as text for user to save manually.

[Agent] Generate a demo pulse using the most recent 24 hours of data as proof-of-concept. Present to user. Validate: Demo pulse rendered. If fails: Present raw exception count and summary instead.

</Workflow - Setup>

<Workflow - Generate Pulse description="Main workflow: scan data, classify exceptions, score, diagnose, recommend, deliver." tools=[run_python, file_write, file_read, open_in_session_tab, web_search] triggers=["what is on fire today", "supply chain pulse", "morning exceptions", "logistics issues", "inventory alerts", "carrier problems", "stockout risk"]

[Agent] Load {{config_directory}}/supply-chain-pulse-config.json to retrieve data source, column mappings, regions, and thresholds. Validate: Config loaded with data source and mappings. If fails: Route to Setup workflow.

[Agent] Pull data for the lookback window (default: last 24 hours) using run_python:

• If SQL connector: query with date filter.
• If file: load and filter by date column. Parse dates with multiple format attempts (ISO 8601, US MM/DD/YYYY, European DD/MM/YYYY). Validate: Data returned with at least 1 row. If fails: Expand lookback to 48 hours. If still empty, report "No data found for this period."

[Agent] Classify each row into exception categories per <Definition - Exception Categories>:

• Compare expected_date vs actual_date for delays.
• Compare inventory vs reorder_point for stockout risk.
• Compare actual demand vs forecast for demand spikes.
• Compare carrier on-time rate vs SLA for carrier breaches. Validate: Each row classified or marked as "normal" (no exception). If fails: Flag rows with missing data as "unclassifiable" and exclude from scoring.

[Agent] Score each exception using the composite formula per <Definition - Severity Score>. Filter to only exceptions at or above severity_threshold. Validate: At least 0 exceptions remain (zero is valid = all clear). If fails: If scoring formula errors, fall back to simple ranking by delay days.

[Decide] Are there zero exceptions above threshold?

• Yes: Generate "All Clear" summary with positive health metrics (on-time rate, fill rate, demand accuracy). Skip to dashboard generation.
• No: Continue to root cause analysis. Validate: Branch determined. If fails: Assume exceptions exist and continue.

[Agent] For each exception, generate a root cause hypothesis based on category:

• Inbound delay: carrier performance history, weather, port congestion.
• Stockout risk: demand spike, supplier fill rate drop, replenishment cycle gap.
• Demand spike: promotion, seasonal, competitor stockout (market share capture).
• Carrier SLA breach: volume surge, lane-specific pattern, systematic underperformance. Validate: Each exception has a root cause hypothesis. If fails: Label as "Root cause undetermined, manual investigation recommended."

[Decide] Is web_search available and are there inbound delay or carrier breach exceptions?

• Yes: Search for port congestion, weather disruptions, or carrier news relevant to affected lanes.
• No: Skip external intelligence. Validate: External context retrieved or skip confirmed. If fails: Skip gracefully. Note "external intelligence unavailable" in report.

[Agent] For each exception, generate a resolution recommendation per <Definition - Resolution>: specific action, ownership role, deadline, cost of action vs inaction. Validate: Each resolution is specific (not generic "investigate"). If fails: Rewrite with concrete steps.

[Agent] Load highcharts and html_design skills. Build interactive HTML dashboard:

• Header: Pulse timestamp, lookback window, total exceptions, critical count.
• Section 1: Severity distribution chart (bar chart by score band).
• Section 2: Exception table (ranked by severity: category, SKU/order, root cause, resolution, owner, deadline).
• Section 3: Carrier scorecard (on-time %, exceptions by carrier).
• Section 4: Inventory health snapshot (stockout risks by location).
• Section 5: External intelligence (if available).
• Footer: data source, config details. Validate: HTML renders without errors. If fails: Fall back to markdown table.

[Agent] Write HTML to {output_directory}/supply-chain-pulse-{date}.html using file_write. Validate: File written. If fails: Output markdown to chat.

[Agent] Open the pulse in session tab using open_in_session_tab. Validate: Tab opened. If fails: Provide file path.

[Decide] Does a previous pulse file exist in {output_directory}/?

• Yes: Compare today's exceptions vs yesterday's. Flag "NEW" exceptions (not in prior pulse) and "RESOLVED" (in prior but not today).
• No: Skip comparison, note this is the first pulse. Validate: Comparison completed or skip confirmed. If fails: Skip comparison.

[Agent] Present plain-text action summary using <Template - Action Summary>. Validate: Summary presented. If fails: N/A.

</Workflow - Generate Pulse>

<Template - Action Summary>

SUPPLY CHAIN PULSE - {{date}}
Critical: {{critical_count}} | Warning: {{warning_count}} | Watch: {{watch_count}}
Top 3 requiring immediate action:
1. {{exception_1_summary}} + {{exception_1_owner}} + {{exception_1_deadline}}
2. {{exception_2_summary}} + {{exception_2_owner}} + {{exception_2_deadline}}
3. {{exception_3_summary}} + {{exception_3_owner}} + {{exception_3_deadline}}
Full dashboard open in tab.

</Template - Action Summary>