sales-data-analysis/.cursor/rules/ai_assistant_guide.md

# AI Assistant Guide for Sales Analysis Template

This guide helps you effectively use Cursor's AI assistant to create sophisticated sales analyses.

## 🎯 Quick Start with AI

### Basic Prompt Structure

When asking the AI to create an analysis, use this structure:

```
Create a [ANALYSIS_TYPE] analysis that:
1. [Specific requirement 1]
2. [Specific requirement 2]
3. Uses the sales_analysis_template patterns
4. Includes [specific visualizations/metrics]
```

### Example Prompts

**Simple Analysis:**
```
Create an annual revenue trend analysis using the template patterns, 
with LTM support and proper chart formatting.
```

**Advanced Analysis:**
```
Create a customer cohort retention analysis that:
1. Groups customers by first purchase month
2. Calculates retention rates for 12 periods
3. Shows revenue retention metrics
4. Creates heatmap visualizations
5. Uses the template's cohort analysis patterns
```

**Multi-Dimensional Analysis:**
```
Create a product performance analysis across regions that:
1. Analyzes top products by revenue
2. Shows regional distribution
3. Calculates growth rates by region
4. Creates multi-panel visualizations
5. Exports results to Excel
```

## 📋 Template-Aware Prompts

The AI automatically knows about:
- `data_loader.py` - Always use this for loading data
- `analysis_utils.py` - Use utilities for formatting, LTM, etc.
- `config.py` - Use config values, never hardcode
- Template patterns - Follows best practices automatically

### What the AI Knows

When you mention the template, the AI will:
- ✅ Use `load_sales_data()` instead of `pd.read_csv()`
- ✅ Use `setup_revenue_chart()` for charts
- ✅ Divide revenue by 1e6 before plotting
- ✅ Use config values from `config.py`
- ✅ Apply exclusion filters if configured
- ✅ Validate data after loading
- ✅ Use LTM patterns correctly

## 🔧 Common AI Tasks

### 1. Create New Analysis Script

**Prompt:**
```
Create a new analysis script called [name].py that:
- Follows the template structure
- Analyzes [specific metric/dimension]
- Creates [type of visualization]
- Uses template utilities
```

**AI will:**
- Copy structure from `analysis_template.py`
- Use proper imports
- Follow template patterns
- Include validation

### 2. Add Advanced Features

**Prompt:**
```
Add statistical significance testing to [analysis].py:
- Compare [group1] vs [group2]
- Show p-values and confidence intervals
- Use statistical_utils functions
```

### 3. Fix Common Issues

**Prompt:**
```
Fix the chart formatting in [analysis].py - it's showing scientific notation.
```

**AI will:**
- Add `data / 1e6` conversion
- Use `setup_revenue_chart()`
- Fix formatting issues

### 4. Enhance Existing Analysis

**Prompt:**
```
Enhance [analysis].py to:
- Add export to Excel functionality
- Include data quality checks
- Add logging
- Generate PDF report
```

## 🚀 Advanced AI Prompts

### Multi-Step Analysis

```
Create a comprehensive customer analysis that:
1. Segments customers using RFM
2. Calculates CLV for each segment
3. Identifies at-risk customers
4. Creates cohort retention analysis
5. Generates PDF report with all charts
```

### Data Quality First

```
Before running the analysis, check data quality:
1. Run data quality report
2. Fix any critical issues
3. Validate configuration
4. Then proceed with analysis
```

### Statistical Analysis

```
Add statistical analysis to [analysis].py:
- Calculate year-over-year growth with significance testing
- Show confidence intervals for forecasts
- Test differences between segments
- Use statistical_utils functions
```

## 💡 Pro Tips

### 1. Reference Existing Examples

```
Create an analysis similar to examples/customer_segmentation.py 
but for product segmentation instead.
```

### 2. Use Template Utilities

```
Use the template's export_utils to save results to Excel,
and report_generator to create a PDF report.
```

### 3. Leverage Cursor Rules

The AI automatically reads `.cursor/rules/` files, so you can say:
```
Follow the advanced_analysis_patterns.md guide to create
a price-volume-mix decomposition analysis.
```

### 4. Iterative Development

```
Start with a basic version, then enhance it:
1. First version: Simple revenue trend
2. Add: Statistical significance
3. Add: Export functionality
4. Add: PDF report generation
```

## 🎨 Visualization Prompts

### Create Specific Chart Types

```
Create a heatmap showing [metric] across [dimension1] and [dimension2],
using seaborn and following template chart formatting.
```

```
Create an interactive Plotly chart for [analysis],
saving it as HTML using the template's interactive chart functions.
```

### Multi-Panel Visualizations

```
Create a 2x2 subplot showing:
- Top left: Revenue trend
- Top right: Customer count trend
- Bottom left: Average order value
- Bottom right: Growth rates
All using template chart formatting.
```

## 📊 Data Analysis Prompts

### Cohort Analysis

```
Create a cohort analysis that:
1. Groups customers by first purchase month
2. Tracks retention for 12 periods
3. Calculates revenue retention
4. Creates retention heatmap
5. Uses examples/cohort_analysis.py as reference
```

### Forecasting

```
Create a revenue forecasting analysis:
1. Prepare time series data
2. Fit trend model
3. Forecast next 12 months
4. Show confidence intervals
5. Use statistical_utils for calculations
```

### Segmentation

```
Create an advanced customer segmentation:
1. Calculate RFM scores
2. Apply clustering algorithm
3. Analyze segment characteristics
4. Create segment visualizations
5. Export segment data to Excel
```

## 🔍 Debugging with AI

### Fix Errors

```
I'm getting [error message] in [file].py.
Fix it using template best practices.
```

### Optimize Performance

```
Optimize [analysis].py for large datasets:
- Use efficient pandas operations
- Add progress indicators
- Consider data sampling if needed
```

### Improve Code Quality

```
Refactor [analysis].py to:
- Use more template utilities
- Follow template patterns better
- Add proper error handling
- Include logging
```

## 📝 Documentation Prompts

### Add Documentation

```
Add comprehensive docstrings to [analysis].py following
the template's documentation style.
```

### Create README

```
Create a README for [analysis].py explaining:
- What it does
- How to run it
- What outputs it generates
- Dependencies required
```

## 🎯 Best Practices for AI Interaction

1. **Be Specific:** Mention template files and utilities by name
2. **Reference Examples:** Point to existing examples when relevant
3. **Iterate:** Start simple, then add complexity
4. **Use Template Terms:** Mention "LTM", "config values", "template patterns"
5. **Ask for Validation:** Request data quality checks and validation

## Example Full Workflow

```
1. "Check my configuration using config_validator.py"
2. "Run data quality report on my data"
3. "Create a revenue trend analysis using template patterns"
4. "Add statistical significance testing to the analysis"
5. "Export results to Excel and generate PDF report"
6. "Create a cohort analysis similar to the example"
```

The AI will guide you through each step using template best practices.

---

**Last Updated:** January 2026  
**For:** Cursor AI users working with sales_analysis_template