Instructions
Step-by-step process for how the Agent should approach tasks. Instructions are the methodology—the "recipe" for analysis.
Why This Matters
Instructions determine:
- Quality of analysis - Good instructions lead to systematic, complete analysis
- Consistency - Same instructions produce similar outputs for similar questions
- Efficiency - Well-designed steps prevent wasted effort on dead ends
- Completeness - Instructions ensure nothing important is missed
Without instructions, an Agent might:
- Jump to conclusions without exploring data first
- Present findings without validating them
- Miss important context or confounding factors
- Present incomplete analysis
The Anatomy of Good Instructions
Good instructions follow a logical flow:
- Understand/Clarify - Get context before diving into data
- Explore - Understand the data available
- Analyze - Execute the core analysis
- Validate - Check the findings for accuracy
- Interpret - Explain what it means
- Recommend - Suggest actions
This mirrors how expert analysts actually think.
Real Example: Poor vs. Good Instructions
Poor Instructions
Instructions:
1. Query the data
2. Calculate metrics
3. Present results
Problems:
- Too vague (which data? which metrics?)
- Missing validation step
- No context gathering
- Might miss important context
Better Instructions
Instructions:
1. Understand the business question
- What decision does this insight inform?
- What stakeholders will use this?
- What time period matters?
2. Explore available data
- What tables contain relevant data?
- Check data quality (nulls, outliers, timing)
- Identify any data gaps
3. Calculate core metrics
- Primary metric relevant to question
- Supporting metrics for context
- Segment breakdowns if relevant
4. Compare to baselines
- vs. historical performance
- vs. targets/goals
- vs. peer benchmarks if available
5. Validate findings
- Check using alternative methods
- Look for data quality issues
- Verify numbers are reasonable
6. Interpret findings
- What does this actually mean?
- Why might this be happening?
- What's NOT explained by the data?
7. Recommend next steps
- What action should be taken?
- What questions remain unanswered?
- What validation would increase confidence?
This is much completer and more systematic.
Instructions Template by Domain
For all Agents, use this structure:
<INSTRUCTIONS>
1. CLARIFICATION/EXPLORATION PHASE
- [Step 1: Understand what's being asked]
- [Step 2: Identify relevant data sources]
- [Step 3: Check data quality/availability]
2. ANALYSIS PHASE
- [Step 1: Calculate primary metrics]
- [Step 2: Segment or drill down]
- [Step 3: Compare to baselines/benchmarks]
3. VALIDATION PHASE
- [Step 1: Cross-check using alternative method]
- [Step 2: Look for data quality issues]
- [Step 3: Verify numbers are reasonable]
4. INTERPRETATION PHASE
- [Step 1: What's the key insight?]
- [Step 2: Why is this happening?]
- [Step 3: What assumptions underlie this insight?]
5. RECOMMENDATION PHASE
- [Step 1: What action should follow?]
- [Step 2: What validation would help?]
- [Step 3: What questions remain?]
</INSTRUCTIONS>
Real Domain Examples: Instructions in Detail
Example 1: Customer Churn Analyst
<INSTRUCTIONS>
1. CLARIFICATION PHASE
- Confirm what "churn" means (subscription ended? No activity X days? Other?)
- Identify time period to analyze
- Confirm which customer segments matter (all? By company size? By geography?)
2. DATA EXPLORATION
- Check subscription table for completeness
- Verify churn event dates are accurate
- Look for data quality issues (missing dates, duplicates)
- Identify which data fields explain churn (reason codes, support tickets, usage)
3. CHURN CALCULATION
- Calculate gross churn rate (% of customers lost)
- Calculate revenue churn (% MRR lost)
- Segment by: company size, industry, acquisition source, tenure
- Calculate cohort retention curves (how long do cohorts typically stay?)
4. ROOT CAUSE ANALYSIS
- Correlate churn with: usage patterns, support tickets, feature adoption
- Identify which segments have highest churn
- Look at churn reason codes (why did customers say they left?)
- Compare to historical churn (is this increase real or seasonal?)
5. VALIDATION
- Cross-check churn calculation using two methods
- Verify any unusual segments have sufficient sample size
- Check if churn reasons align with observed behaviors
- Look for seasonal patterns (Jan always higher, Q4 lower, etc.)
6. INTERPRETATION
- What's the key churn trend?
- Which segments are most at-risk?
- What's the likely cause for each segment?
- What's surprising or unexpected?
7. RECOMMENDATIONS
- For each high-risk segment: specific retention actions
- Early warning signals to monitor
- What further analysis would help?
</INSTRUCTIONS>
Example 2: Inventory Optimization Analyst
<INSTRUCTIONS>
1. CLARIFICATION PHASE
- Confirm scope: all SKUs or specific categories?
- Which locations/channels are in scope?
- What's the planning horizon (1 week? 1 month? Quarter?)
- Are there business events (promotions, seasonality) to account for?
2. INVENTORY DATA EXPLORATION
- Assess current inventory levels by location
- Understand sales velocity (units/day) for each SKU
- Check for data quality (phantom inventory? Timing lags?)
- Identify lead times and replenishment cycles
- Calculate holding costs (storage, capital, spoilage)
3. DEMAND FORECASTING
- Project demand for each SKU (normal trend + seasonality)
- Account for known events (promotions, seasonality)
- Estimate demand variability/risk (fast movers vs. slow movers)
- Calculate safety stock needed to cover variability
4. OPTIMAL INVENTORY CALCULATION
- Calculate Economic Order Quantity (EOQ) for each SKU
- Determine safety stock levels based on demand variability + lead time
- Set target inventory levels (EOQ + safety stock)
- Compare current levels to targets
5. OPPORTUNITY IDENTIFICATION
- SKUs below safety stock (stockout risk)
- SKUs above 2x target inventory (excess/dead stock)
- Slow-moving items approaching obsolescence
- Opportunities to rebalance across locations
6. VALIDATION
- Verify calculations using two methods (if possible)
- Spot-check a few SKUs with domain experts (are targets reasonable?)
- Check if historical stockout/overstock patterns align with model
- Verify any unusual recommendations make sense
7. RECOMMENDATIONS
- Immediate replenishment needs (next 1-2 weeks)
- Rebalancing opportunities (move inventory between locations)
- Items to hold/reduce orders on
- Next steps for improvement
</INSTRUCTIONS>
Example 3: Manufacturing Quality Analyst
<INSTRUCTIONS>
1. CLARIFICATION PHASE
- Confirm quality metrics to focus on (defect rate? Cpk? First-pass yield?)
- Identify which production lines or time periods
- Confirm inspection method (100% automated? Sampling?)
- Are there known recent changes (new supplier? Equipment?) to investigate?
2. DATA QUALITY ASSESSMENT
- Check inspection data completeness
- Verify time stamps are accurate
- Assess inspection method consistency
- Look for any data gaps or anomalies
3. QUALITY METRICS CALCULATION
- Calculate defect rate (% or PPM)
- Calculate process capability (Cpk)
- Calculate first-pass yield
- Segment by: production line, shift, time period
4. TREND ANALYSIS
- Create control charts (looking for out-of-control signals)
- Identify when quality changed
- Distinguish normal variation from special cause variation
- Look for patterns (by shift? by supplier batch? by equipment?)
5. ROOT CAUSE ANALYSIS
- For each quality issue, identify potential causes
- Correlate quality with: process variables, equipment maintenance, material supplier
- Interview production teams about recent changes
- Look for relationships (temperature drift + dimensional issues?)
6. VALIDATION
- Verify control chart signals (are they real or noise?)
- Cross-check data from multiple sources
- Confirm suspected root causes with observation (if possible)
7. RECOMMENDATIONS
- For each identified issue: specific corrective action
- Expected impact on quality metrics
- Timeline and resource requirements
- What follow-up validation is needed?
</INSTRUCTIONS>
Instructions Design Principles
-
Logical Flow Instructions should follow a natural progression:
- First understand what you're trying to solve
- Then explore what data you have
- Then do the analysis
- Then validate it
- Then interpret it Bad flow: "Calculate metrics, then explore data, then validate" (backwards!)
-
Anticipate Failure Points Instructions should address common mistakes:
- "Don't compare physicians without risk adjustment" (prevents unfair doctor-shaming)
- "Always verify sample size before making claims" (prevents statistical errors)
- "Account for seasonality before calling something a trend" (prevents false alarms)
-
Build in Quality Gates Instructions should include validation steps:
- Cross-check using two methods
- Verify unusual findings
- Check for data quality issues
- Compare to historical patterns
-
Balance Flexibility and Structure Instructions should:
- Provide enough structure for consistency
- Allow flexibility for different questions
- Be specific enough to be useful
- Not be so rigid they prevent good judgment
Good: "Calculate churn by segment (they may vary significantly)" Bad: "Calculate exactly 5 segments using these exact fields"
Common Instruction Mistakes
| Mistake | Problem | Example | Fix |
|---|---|---|---|
| Too vague | Agent doesn't know what to do | "Analyze the data" | "Calculate churn rate by company size and compare to 3-month average" |
| No validation step | Agent doesn't check work | Missing cross-validation | Add step: "Verify using alternative calculation method" |
| Missing context gathering | Agent misses important business context | Doesn't ask about known promotions | Add step: "Confirm any planned events affecting expected patterns" |
| No prioritization | Agent might analyze irrelevant things | Spend time on 100th-order effects | Add step: "Focus first on [high-impact area], then drill deeper if time allows" |
| Not domain-aware | Agent doesn't account for domain-specific issues | Comparing small hospitals to large ones without risk adjustment | Add step: "Risk-adjust all comparisons for [domain-specific factor]" |