@quarri/claude-data-tools 1.0.2 → 1.1.1

package/skills/quarri-analyze/SKILL.md

@@ -0,0 +1,274 @@
+---
+description: Run complete data analysis pipeline orchestrating query, insights, and charts
+globs:
+alwaysApply: false
+---
+
+# /quarri-analyze - Full Analysis Pipeline
+
+Orchestrate a complete data analysis pipeline by coordinating query generation, statistical analysis, business insights, and visualization.
+
+## When to Use
+
+Use `/quarri-analyze` when users want comprehensive analysis:
+- "Analyze our sales trends"
+- "What's driving customer churn?"
+- "Give me insights on revenue performance"
+- "Help me understand our order patterns"
+
+This is more powerful than `/quarri-query` as it provides statistics, visualizations, and actionable insights.
+
+## Orchestration Flow
+
+```
+/quarri-analyze
+    │
+    ├── 1. /quarri-query
+    │       └── Generate SQL, fetch schema, execute query
+    │
+    ├── 2. /quarri-insights
+    │       └── Statistical analysis + business interpretation
+    │
+    └── 3. /quarri-chart (if visualization warranted)
+            └── Chart recommendation + configuration
+```
+
+### Stage 1: Query (via /quarri-query)
+
+Generate and execute SQL for the analysis question:
+1. Fetch schema using `quarri_get_schema`
+2. Search for relevant metrics using `quarri_search_metrics`
+3. Generate SQL following star schema patterns
+4. Execute using `quarri_execute_sql`
+
+### Stage 2: Insights (via /quarri-insights)
+
+Analyze the query results:
+- Descriptive statistics for numeric columns
+- Distribution and outlier analysis
+- Correlation between variables
+- Time series trends if applicable
+- Business interpretation and recommendations
+
+### Stage 3: Chart (via /quarri-chart)
+
+If data warrants visualization:
+- Apply chart decision tree
+- Generate appropriate chart configuration
+- Recommend alternatives if applicable
+
+## MECE Framework for Complex Analysis
+
+When analyzing complex business questions, structure the breakdown using the MECE principle:
+- **Mutually Exclusive**: Categories don't overlap
+- **Collectively Exhaustive**: All possibilities covered
+
+### MECE Application Examples
+
+#### Revenue Analysis
+"Why is revenue changing?"
+```
+Revenue Drivers (MECE Breakdown)
+├── Volume Drivers
+│   ├── Customer count
+│   ├── Order frequency per customer
+│   └── Units per order
+├── Price Drivers
+│   ├── Unit price
+│   ├── Product mix shift
+│   └── Discount rates
+└── External Factors
+    ├── Seasonality
+    ├── Market conditions
+    └── Competition
+```
+
+#### Customer Churn Analysis
+"What's causing churn?"
+```
+Churn Factors (MECE Breakdown)
+├── Product Issues
+│   ├── Quality problems
+│   ├── Feature gaps
+│   └── Performance issues
+├── Service Issues
+│   ├── Support quality
+│   ├── Response time
+│   └── Resolution rate
+├── Price Issues
+│   ├── Absolute cost
+│   ├── Perceived value
+│   └── Competitor pricing
+└── External Factors
+    ├── Business closure
+    ├── Changed needs
+    └── Market exit
+```
+
+#### Sales Performance
+"Why are sales underperforming?"
+```
+Sales Performance (MECE Breakdown)
+├── Lead Generation
+│   ├── Marketing qualified leads
+│   ├── Inbound inquiries
+│   └── Outbound prospecting
+├── Conversion Rate
+│   ├── Lead to opportunity
+│   ├── Opportunity to proposal
+│   └── Proposal to close
+└── Deal Size
+    ├── Initial contract value
+    ├── Upsell/cross-sell
+    └── Discounting
+```
+
+### When to Apply MECE
+
+Apply MECE structuring when:
+1. Question involves "why" (root cause analysis)
+2. Multiple factors could explain the outcome
+3. User needs comprehensive coverage
+4. Decision-making requires evaluating alternatives
+
+For simple queries ("show revenue by region"), skip MECE and provide direct analysis.
+
+## Workflow
+
+```
+1. Parse the analysis question
+   - Identify primary metric/measure
+   - Identify dimensions/breakdowns
+   - Determine time scope
+
+2. Execute /quarri-query
+   - Generate appropriate SQL
+   - Execute and retrieve data
+   - Validate results
+
+3. Execute /quarri-insights
+   - Run statistical analysis
+   - Identify patterns
+   - Generate business insights
+
+4. Determine if visualization needed
+   - Data has clear visual pattern?
+   - More than 3 data points?
+   - User explicitly requested chart?
+
+5. If yes, execute /quarri-chart
+   - Select appropriate chart type
+   - Generate configuration
+
+6. Synthesize comprehensive report
+   - Combine all findings
+   - Apply MECE structure if complex question
+   - Prioritize actionable recommendations
+```
+
+## Output Format
+
+```markdown
+## Analysis: [Question Summary]
+
+### Query
+```sql
+[SQL generated by /quarri-query]
+```
+[Brief explanation of what the query retrieves]
+
+### Data Summary
+- **Rows**: [count]
+- **Date range**: [range]
+- **Key dimensions**: [list]
+
+### Statistical Findings
+[From /quarri-insights]
+- [Key statistic 1]
+- [Key statistic 2]
+- [Key statistic 3]
+
+### MECE Breakdown (if applicable)
+[Structured analysis of drivers/factors]
+
+### Business Insights
+
+#### Key Finding
+**[Most important takeaway with specific numbers]**
+
+#### Additional Insights
+1. **[Insight type]**: [Specific finding]
+   - Implication: [What it means]
+   - Action: [What to do]
+
+2. **[Insight type]**: [Specific finding]
+   - Implication: [What it means]
+   - Action: [What to do]
+
+### Visualization
+[From /quarri-chart if applicable]
+[Chart type recommendation with rationale]
+[Configuration or URL]
+
+### Recommended Next Steps
+1. [Immediate action]
+2. [Follow-up analysis]
+3. [Deeper investigation if warranted]
+```
+
+## Example: Full Analysis
+
+**User**: "Analyze why revenue dropped last month"
+
+**Analysis Output**:
+
+### Query
+```sql
+SELECT
+    DATE_TRUNC('week', order_date) as week,
+    product_category,
+    COUNT(*) as order_count,
+    COUNT(DISTINCT customer_id) as customers,
+    SUM(revenue) as revenue,
+    AVG(order_value) as avg_order_value
+FROM quarri.bridge
+WHERE order_date >= DATE '2024-11-01'
+GROUP BY week, product_category
+ORDER BY week, product_category
+```
+
+### MECE Breakdown: Revenue Decline Drivers
+
+```
+Revenue = Customers × Orders/Customer × Revenue/Order
+
+Analysis by Driver:
+├── Customer Count: -8% (from 1,245 to 1,146)
+│   └── PRIMARY DRIVER: New customer acquisition dropped
+├── Order Frequency: -2% (from 2.3 to 2.25 orders/customer)
+│   └── Minor decline, within normal range
+└── Revenue per Order: +1% (from $89 to $90)
+    └── Stable, slight increase
+```
+
+### Key Finding
+**Customer acquisition dropped 8%, accounting for 75% of the revenue decline. New customer count fell from 312 to 198 (-37%).**
+
+### Recommended Actions
+1. **Immediate**: Review marketing spend and campaign performance from last month
+2. **This week**: Analyze acquisition channel performance (paid vs organic)
+3. **Follow-up**: Compare conversion rates by channel to identify where leads are dropping
+
+## Error Handling
+
+- If query returns no data, suggest adjusting filters or date range
+- If statistical analysis fails, report data quality issues
+- If MECE breakdown unclear, ask clarifying questions
+- Always provide partial results if some stages succeed
+
+## Integration
+
+This skill orchestrates:
+- `/quarri-query` for data retrieval
+- `/quarri-insights` for statistical analysis and business interpretation
+- `/quarri-chart` for visualization recommendations

package/skills/quarri-chart/SKILL.md

@@ -0,0 +1,374 @@
+---
+description: Generate interactive Plotly charts and open them in the browser
+globs:
+alwaysApply: false
+---
+
+# /quarri-chart - Interactive Chart Generation
+
+Generate data visualizations as interactive HTML files and open them in the default browser.
+
+## When to Use
+
+Use `/quarri-chart` when users want visualizations:
+- "Create a chart of revenue by month"
+- "Visualize customer distribution"
+- "Show me a graph of this data"
+- "Chart sales by category"
+
+## Primary Workflow (DEFAULT)
+
+### Step 1: Query the data
+```sql
+SELECT category, SUM(sales) as total_sales
+FROM orders
+GROUP BY category
+ORDER BY total_sales DESC
+```
+
+### Step 2: Generate HTML with Plotly
+Write an HTML file to `/tmp/quarri_chart.html`:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>[Chart Title]</title>
+    <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 40px; background: #f5f5f5; }
+        h1 { color: #1a1a2e; text-align: center; margin-bottom: 10px; }
+        .subtitle { color: #666; text-align: center; margin-bottom: 30px; }
+        #chart { width: 100%; max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); padding: 20px; }
+    </style>
+</head>
+<body>
+    <h1>[Chart Title]</h1>
+    <p class="subtitle">Data from [database_name]</p>
+    <div id="chart"></div>
+    <script>
+        var data = [{
+            x: [/* labels */],
+            y: [/* values */],
+            type: 'bar',
+            marker: { color: '#4F46E5' }
+        }];
+
+        var layout = {
+            title: '',
+            xaxis: { title: '[X Label]' },
+            yaxis: { title: '[Y Label]', tickformat: '$,.0f' },
+            margin: { t: 40, b: 60, l: 80, r: 40 }
+        };
+
+        var config = { responsive: true, displayModeBar: true };
+        Plotly.newPlot('chart', data, layout, config);
+    </script>
+</body>
+</html>
+```
+
+### Step 3: Open in browser
+```bash
+open /tmp/quarri_chart.html
+```
+
+On different platforms:
+- **macOS**: `open /tmp/quarri_chart.html`
+- **Linux**: `xdg-open /tmp/quarri_chart.html`
+- **Windows**: `start /tmp/quarri_chart.html`
+
+## Chart Type Selection
+
+### Decision Tree
+
+```
+START: What is the primary analysis goal?
+
+1. TRENDS OVER TIME?
+   └─→ Single series? → LINE CHART
+   └─→ Multiple series? → MULTI-LINE
+   └─→ Cumulative? → AREA CHART
+
+2. COMPARING CATEGORIES?
+   └─→ 2-7 categories → VERTICAL BAR
+   └─→ 8-15 categories → HORIZONTAL BAR
+   └─→ 15+ categories → TOP N + "Other"
+
+3. SHOWING DISTRIBUTION?
+   └─→ Continuous data → HISTOGRAM
+   └─→ Categorical → BAR (sorted)
+
+4. PARTS OF A WHOLE?
+   └─→ 2-6 parts → PIE/DONUT
+   └─→ 7+ parts → STACKED BAR
+
+5. RELATIONSHIP BETWEEN VARIABLES?
+   └─→ Two numeric → SCATTER PLOT
+```
+
+## Plotly Templates
+
+### Bar Chart
+```javascript
+var data = [{
+    x: ['Category A', 'Category B', 'Category C'],
+    y: [450000, 380000, 290000],
+    type: 'bar',
+    marker: {
+        color: ['#4F46E5', '#7C3AED', '#A78BFA']
+    },
+    text: ['$450K', '$380K', '$290K'],
+    textposition: 'auto'
+}];
+
+var layout = {
+    title: 'Sales by Category',
+    xaxis: { title: 'Category' },
+    yaxis: { title: 'Sales ($)', tickformat: '$,.0f' }
+};
+```
+
+### Horizontal Bar (many categories)
+```javascript
+var data = [{
+    y: ['Product A', 'Product B', 'Product C', 'Product D', 'Product E'],
+    x: [85000, 72000, 65000, 58000, 45000],
+    type: 'bar',
+    orientation: 'h',
+    marker: { color: '#4F46E5' }
+}];
+
+var layout = {
+    title: 'Top Products by Revenue',
+    xaxis: { title: 'Revenue ($)', tickformat: '$,.0f' },
+    margin: { l: 120 }
+};
+```
+
+### Line Chart (time series)
+```javascript
+var data = [{
+    x: ['2024-01', '2024-02', '2024-03', '2024-04', '2024-05', '2024-06'],
+    y: [120000, 135000, 128000, 145000, 160000, 175000],
+    type: 'scatter',
+    mode: 'lines+markers',
+    line: { color: '#4F46E5', width: 3 },
+    marker: { size: 8 }
+}];
+
+var layout = {
+    title: 'Monthly Revenue Trend',
+    xaxis: { title: 'Month' },
+    yaxis: { title: 'Revenue ($)', tickformat: '$,.0f' }
+};
+```
+
+### Multi-Line Chart
+```javascript
+var data = [
+    {
+        x: ['Jan', 'Feb', 'Mar', 'Apr'],
+        y: [100, 120, 115, 140],
+        name: 'Product A',
+        type: 'scatter',
+        mode: 'lines+markers'
+    },
+    {
+        x: ['Jan', 'Feb', 'Mar', 'Apr'],
+        y: [80, 95, 110, 120],
+        name: 'Product B',
+        type: 'scatter',
+        mode: 'lines+markers'
+    }
+];
+
+var layout = {
+    title: 'Product Comparison',
+    xaxis: { title: 'Month' },
+    yaxis: { title: 'Sales' }
+};
+```
+
+### Pie/Donut Chart
+```javascript
+var data = [{
+    labels: ['Technology', 'Furniture', 'Office Supplies'],
+    values: [5471124, 4730801, 4144724],
+    type: 'pie',
+    hole: 0.4,  // Remove for regular pie
+    marker: {
+        colors: ['#4F46E5', '#10B981', '#F59E0B']
+    },
+    textinfo: 'label+percent'
+}];
+
+var layout = {
+    title: 'Sales Distribution by Category'
+};
+```
+
+### Scatter Plot
+```javascript
+var data = [{
+    x: [/* x values */],
+    y: [/* y values */],
+    mode: 'markers',
+    type: 'scatter',
+    marker: {
+        size: 10,
+        color: '#4F46E5',
+        opacity: 0.7
+    }
+}];
+
+var layout = {
+    title: 'Correlation Analysis',
+    xaxis: { title: 'Variable X' },
+    yaxis: { title: 'Variable Y' }
+};
+```
+
+### Grouped Bar Chart
+```javascript
+var data = [
+    {
+        x: ['Q1', 'Q2', 'Q3', 'Q4'],
+        y: [120, 150, 180, 200],
+        name: '2023',
+        type: 'bar'
+    },
+    {
+        x: ['Q1', 'Q2', 'Q3', 'Q4'],
+        y: [140, 165, 195, 220],
+        name: '2024',
+        type: 'bar'
+    }
+];
+
+var layout = {
+    title: 'Year over Year Comparison',
+    barmode: 'group'
+};
+```
+
+## Color Palettes
+
+```javascript
+// Primary (single series)
+const PRIMARY = '#4F46E5';
+
+// Categorical (multiple series)
+const CATEGORICAL = ['#4F46E5', '#10B981', '#F59E0B', '#EF4444', '#8B5CF6', '#EC4899', '#06B6D4', '#84CC16'];
+
+// Sequential (gradient)
+const SEQUENTIAL = ['#E0E7FF', '#A5B4FC', '#818CF8', '#6366F1', '#4F46E5', '#4338CA', '#3730A3'];
+
+// Diverging (positive/negative)
+const DIVERGING_NEG = '#EF4444';
+const DIVERGING_POS = '#10B981';
+```
+
+## Number Formatting
+
+```javascript
+// Currency
+tickformat: '$,.0f'      // $1,234,567
+tickformat: '$,.2f'      // $1,234,567.89
+tickformat: '$~s'        // $1.2M
+
+// Percentages
+tickformat: '.1%'        // 45.2%
+
+// Large numbers
+tickformat: '~s'         // 1.2M, 3.4K
+```
+
+## Complete Example
+
+For "Show me sales by category":
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Sales by Category</title>
+    <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+    <style>
+        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; margin: 40px; background: #f5f5f5; }
+        h1 { color: #1a1a2e; text-align: center; margin-bottom: 10px; }
+        .subtitle { color: #666; text-align: center; margin-bottom: 30px; font-size: 14px; }
+        #chart { width: 100%; max-width: 900px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); padding: 20px; }
+    </style>
+</head>
+<body>
+    <h1>Superstore Sales by Category</h1>
+    <p class="subtitle">Total: $14.3M across 51,290 orders</p>
+    <div id="chart"></div>
+    <script>
+        var data = [{
+            x: ['Technology', 'Furniture', 'Office Supplies'],
+            y: [5471124.24, 4730801.23, 4144724.04],
+            type: 'bar',
+            marker: {
+                color: ['#4F46E5', '#7C3AED', '#A78BFA']
+            },
+            text: ['$5.47M', '$4.73M', '$4.14M'],
+            textposition: 'outside',
+            textfont: { size: 14, color: '#374151' }
+        }];
+
+        var layout = {
+            xaxis: { title: 'Category', tickfont: { size: 12 } },
+            yaxis: {
+                title: 'Sales ($)',
+                tickformat: '$,.0f',
+                tickfont: { size: 11 }
+            },
+            margin: { t: 40, b: 80, l: 100, r: 40 },
+            plot_bgcolor: 'white',
+            paper_bgcolor: 'white'
+        };
+
+        var config = {
+            responsive: true,
+            displayModeBar: true,
+            modeBarButtonsToRemove: ['lasso2d', 'select2d']
+        };
+
+        Plotly.newPlot('chart', data, layout, config);
+    </script>
+</body>
+</html>
+```
+
+Then run:
+```bash
+open /tmp/quarri_chart.html
+```
+
+## Alternative Outputs
+
+### QuickChart URL (for sharing/embedding)
+When user specifically needs a URL:
+```
+https://quickchart.io/chart?c={type:'bar',data:{labels:['A','B','C'],datasets:[{data:[10,20,15]}]}}
+```
+
+### ASCII Chart (terminal only)
+When user is in a terminal-only environment:
+```
+Sales by Category
+
+Technology      |████████████████████████████████████████ $5.47M
+Furniture       |██████████████████████████████████      $4.73M
+Office Supplies |██████████████████████████████          $4.14M
+                 0              $3M              $6M
+```
+
+## Integration
+
+Charts work best when combined with:
+- `/quarri-query`: Get data first, then visualize
+- `/quarri-analyze`: Called as part of full analysis pipeline
+- `/quarri-insights`: Visual support for statistical findings