Features
Explanation Engine
The Explanation Engine uses AI to answer natural language questions about your store's behavior. Understand why orders, products, or operations behaved in certain ways.
Explanation Engine
The Explanation Engine uses AI to answer natural language questions about your store's behavior. Understand why orders, products, or operations behaved in certain ways.
Overview
When something unexpected happens, you need to understand why. The Explanation Engine provides:
- Natural Language Queries: Ask questions in plain English
- Multi-Step Analysis: AI traces through decision paths
- Contributing Factor Identification: Understand what influenced outcomes
- Actionable Recommendations: Get suggestions for improvement
- Data-Backed Explanations: Answers grounded in your actual data
Getting Started
Accessing the Engine
- Navigate to Explanation Engine in the sidebar
- Select a scope (Orders or Products)
- Type your question
- Review the AI's explanation
Interface Overview
┌─────────────────────────────────────────────────────────────────┐
│ EXPLANATION ENGINE │
│ │
│ Scope: [Orders ▾] │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Ask a question about your orders... │ │
│ │ │ │
│ │ "Why did order #1234 take 5 days to fulfill?" │ │
│ │ [Ask] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ EXAMPLE QUESTIONS │
│ • Why was this order split into multiple shipments? │
│ • What caused the refund spike last week? │
│ • Why did fulfillment slow down on Tuesday? │
│ • Which products contributed most to returns this month? │
└─────────────────────────────────────────────────────────────────┘
Query Scopes
Orders Scope
Questions about order-related behavior:
| Question Type | Examples |
|---|---|
| Individual Orders | "Why did order #1234 get cancelled?" |
| Order Patterns | "Why are orders splitting more often?" |
| Fulfillment | "What's causing fulfillment delays?" |
| Refunds | "Why did refunds increase last week?" |
| Revenue | "What drove the revenue drop on Monday?" |
Products Scope
Questions about product-related behavior:
| Question Type | Examples |
|---|---|
| Sales Performance | "Why did product X sales drop?" |
| Inventory | "What led to the stockout of product Y?" |
| Pricing | "How did the price change affect sales?" |
| Returns | "Why is product Z being returned so much?" |
| Variants | "Which variant performs best and why?" |
Asking Questions
Writing Effective Questions
Good questions are:
- Specific: Reference particular items, dates, or metrics
- Bounded: Focus on one aspect at a time
- Observable: Based on something you noticed
Good examples:
- "Why did order #5678 take 4 days to ship when our average is 1 day?"
- "What caused the 15% drop in conversion rate on January 10th?"
- "Which products are driving the increase in returns this quarter?"
Less effective:
- "Why are sales bad?" (too vague)
- "Tell me everything about my store" (too broad)
- "What will happen next month?" (speculation, not explanation)
Question Suggestions
PeerScripts suggests questions based on:
- Recent anomalies detected
- Significant metric changes
- Common patterns in your data
Understanding Explanations
Explanation Structure
┌─────────────────────────────────────────────────────────────────┐
│ EXPLANATION │
│ │
│ Question: "Why did order #5678 take 4 days to fulfill?" │
│ │
│ ───────────────────────────────────────────────────────────── │
│ │
│ SUMMARY │
│ Order #5678 experienced a longer-than-normal fulfillment time │
│ due to a combination of inventory location and processing │
│ delays. │
│ │
│ CONTRIBUTING FACTORS │
│ │
│ 1. INVENTORY LOCATION (Primary Factor) │
│ The ordered item (SKU: PWH-001-BLK) was only available at │
│ the secondary warehouse, which has a 2-day processing SLA │
│ compared to 4 hours at the primary location. │
│ Impact: +1.5 days │
│ │
│ 2. CARRIER DELAY │
│ The shipment was handed to carrier on Day 2, but the │
│ carrier experienced regional delays due to weather. │
│ Impact: +1 day │
│ │
│ 3. WEEKEND TIMING │
│ The order was placed Friday evening. Processing didn't │
│ begin until Monday morning. │
│ Impact: +1.5 days │
│ │
│ DECISION PATH │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Order Received → Check Primary Inventory (Not Found) → │ │
│ │ Check Secondary Inventory (Found) → Route to Secondary │ │
│ │ Warehouse → Wait for Processing (Weekend) → Ship → │ │
│ │ Carrier Delay → Delivered │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ RECOMMENDATIONS │
│ • Consider stocking high-velocity items at primary location │
│ • Review secondary warehouse SLA │
│ • Set customer expectations for weekend order timing │
│ │
│ [Create Ticket] [Ask Follow-up] [Export] │
└─────────────────────────────────────────────────────────────────┘
Explanation Components
| Component | Description |
|---|---|
| Summary | Brief answer to your question |
| Contributing Factors | What caused the outcome, ranked by impact |
| Decision Path | Step-by-step trace of what happened |
| Recommendations | Actionable suggestions |
| Data Points | Specific data that supports the explanation |
Following Up
Ask Follow-up Questions
Dig deeper into explanations:
- Read the initial explanation
- Click Ask Follow-up
- Ask a more specific question
- Context from previous question is preserved
Example Follow-up Flow
Initial: "Why did fulfillment slow down this week?"
→ Explanation identifies inventory issues
Follow-up: "Which specific products caused the inventory issues?"
→ Lists products with stockouts or location problems
Follow-up: "What would it take to prevent this for product X?"
→ Specific recommendations for that product
Query History
Viewing Past Queries
Access your question history:
┌─────────────────────────────────────────────────────────────────┐
│ QUERY HISTORY [Filter] │
│ │
│ Today │
│ ├─ "Why did order #5678 take 4 days to fulfill?" │
│ │ 2:30 PM • Orders • [View] │
│ │ │
│ ├─ "What caused the refund spike last week?" │
│ │ 11:15 AM • Orders • [View] │
│ │ │
│ Yesterday │
│ ├─ "Why is product SKU-123 being returned so often?" │
│ │ 4:45 PM • Products • [View] │
│ │ │
│ └─ "Which products drove revenue this month?" │
│ 9:00 AM • Products • [View] │
│ │
│ Showing 1-4 of 28 [< Prev] [Next >] │
└─────────────────────────────────────────────────────────────────┘
Saving Important Explanations
For explanations you want to reference later:
- Click Save on the explanation
- Add optional notes
- Access from Saved Explanations
Data Inspection
Raw Data View
For technical users, inspect the underlying data:
- Click Show Raw Data (developer mode)
- View the actual data points used
- Verify the AI's conclusions
┌─────────────────────────────────────────────────────────────────┐
│ RAW DATA │
│ │
│ Order #5678: │
│ { │
│ "created_at": "2025-01-10T18:30:00Z", │
│ "fulfilled_at": "2025-01-14T14:22:00Z", │
│ "fulfillment_location": "warehouse_b", │
│ "carrier": "ups_ground", │
│ "line_items": [ │
│ { "sku": "PWH-001-BLK", "quantity": 1 } │
│ ], │
│ "inventory_at_order": { │
│ "warehouse_a": 0, │
│ "warehouse_b": 12 │
│ } │
│ } │
└─────────────────────────────────────────────────────────────────┘
Performance Metrics
Understanding Processing Time
Complex questions may take longer to process:
| Complexity | Time | Example |
|---|---|---|
| Simple | 5-10s | Single order lookup |
| Medium | 15-30s | Pattern across multiple orders |
| Complex | 30-60s | Cross-referencing multiple data sources |
Query Status
┌─────────────────────────────────────────────────────────────────┐
│ PROCESSING QUERY │
│ │
│ "What caused the refund spike last week?" │
│ │
│ [████████████░░░░░░░░] 60% │
│ │
│ Status: Analyzing 847 orders from last week │
│ • Gathering refund data ✓ │
│ • Analyzing patterns ✓ │
│ • Identifying factors... │
│ • Generating explanation... │
└─────────────────────────────────────────────────────────────────┘
Integration
From Other Features
Access the Explanation Engine from:
- Store Health: Click "Explain" on any anomaly
- Dashboard: Click "Why?" on metric changes
- Catalog Intelligence: Explain issue patterns
Creating Actions
Turn insights into actions:
- Review the explanation
- Click Create Ticket for recommendations
- Track implementation
Best Practices
Getting Good Answers
- Be specific - Include dates, IDs, or exact metrics
- One question at a time - Don't combine multiple questions
- Use scope appropriately - Choose Orders vs Products correctly
- Follow up - Dig deeper into initial answers
When to Use
| Situation | Use Explanation Engine |
|---|---|
| Anomaly detected | Ask why it happened |
| Metric changed | Understand the cause |
| Customer complaint | Trace what happened |
| Planning changes | Understand current state |
When Not to Use
| Situation | Better Alternative |
|---|---|
| Find specific data | Use search or reports |
| Future predictions | Use analytics tools |
| Technical debugging | Use Code Editor |
| General questions | Use documentation |
Limitations
What the Engine Cannot Do
- Predict the future: Only explains past events
- Access external data: Limited to PeerScripts data
- Make changes: Can only explain, not act
- Real-time analysis: Uses synced data, slight delay
Data Requirements
For accurate explanations, ensure:
- Data is synced and up-to-date
- Sufficient history exists (7+ days)
- Relevant data types are tracked
Troubleshooting
"Not Enough Data"
- Check if data scope is synced
- Verify date range has data
- Try a broader question
Explanation Seems Wrong
- Check the raw data view
- Verify data accuracy in Shopify
- Try rephrasing the question
- Report issues for improvement
Query Timeout
- Simplify the question
- Narrow the date range
- Try during off-peak hours
Related Features
- Store Health - Anomaly detection
- Catalog Intelligence - Product analysis
- Changes Tracking - What changed