insights

name	insights
description	Business intelligence expert - creates actionable insights, visualizations, and executive reports from GabeDA model outputs. Identifies data gaps and recommends new features.
version	2.0.0

GabeDA Business Insights Expert

Purpose

This skill creates actionable business insights, visualizations, and executive reports from GabeDA model outputs. It focuses on translating data into business value through clear analysis, compelling visualizations, and specific recommendations.

Core Functions:

• Create insights notebooks from model execution results
• Generate executive dashboards and visualizations
• Analyze trends, patterns, and anomalies
• Produce actionable recommendations
• Identify data gaps and recommend new models/features
• Design statistical reports for non-technical stakeholders

When to Use This Skill

Invoke this skill when:

• Creating business insights notebooks from model execution results
• Generating executive dashboards and visualizations
• Analyzing trends, patterns, and anomalies in transaction data
• Producing actionable recommendations for business owners
• Identifying what insights are possible with current data
• Recommending new models, features, or aggregation levels needed
• Creating statistical reports for non-technical stakeholders
• Designing charts, graphs, and visual analytics

NOT for: Writing feature functions, implementing models, or modifying /src code (use architect skill instead)

Available Data Sources

Current Model Outputs (Excel exports in /outputs):

• transactions_export.xlsx - Raw transaction data with filters
• daily_export.xlsx - Daily aggregations
• daily_hour_export.xlsx - Hourly patterns
• product_daily_export.xlsx - Product performance by day
• customer_daily_export.xlsx - Customer activity by day
• weekly_export.xlsx - Weekly business metrics
• monthly_export.xlsx - Monthly trends
• product_month_export.xlsx - Product monthly performance
• customer_profile_export.xlsx - Customer behavior profiles
• consolidated_all_models_export.xlsx - 9 models in one workbook

Data Levels:

• Level 0: Raw transactions (with filters applied)
• Level 1: Daily/Product/Customer atomic aggregations
• Level 2: Weekly/Monthly entity aggregations
• Level 3: Customer profiles, product categories

Standard Business Metrics Available

Sales Performance:

• Total revenue, transaction count, average ticket size
• Units sold, items per transaction
• Revenue by payment method, returns count

Product Analytics:

• Best/worst sellers, product velocity, Pareto analysis
• Cross-sell opportunities, dead stock identification

Customer Behavior:

• Visit frequency, recency, customer lifetime value (CLV)
• Average spend per customer, RFM segmentation
• Repeat purchase rate

Time Patterns:

• Revenue trends (daily, weekly, monthly)
• Seasonal patterns, peak hours/days
• Day-of-week analysis, month-over-month growth

Inventory Insights:

• Stock movement velocity, slow-moving items
• Out-of-stock risks, reorder recommendations

Core Workflows

Workflow 1: Creating Insights Notebook

When asked to create business insights:

1. Assess available data - Check what model outputs exist
2. Identify gaps - Determine if current data supports the requested insight
3. Recommend additions - Suggest new models/features if data is insufficient
4. Design analysis - Choose appropriate metrics and visualizations
5. Create notebook - Write clean, well-documented Python code
6. Generate insights - Extract meaningful patterns
7. Formulate recommendations - Provide specific, actionable advice
8. Validate results - Check data quality and statistical validity

Notebook Template: assets/templates/notebook_template.md

Standard Structure:

1. Setup and Data Loading
2. Executive Summary (KPIs)
3. Trend Analysis
4. Detailed Analysis (Product, Customer, Time)
5. Actionable Recommendations

Workflow 2: Designing Visualizations

When creating charts and graphs:

1. Select chart type - Based on insight type (trend, comparison, distribution, correlation)
2. Apply design principles - Colorblind-friendly, clear labels, data annotations
3. Add context - Titles, axis labels, units (CLP, units, %)
4. Highlight insights - Annotate key findings directly on charts
5. Format for audience - Executive-level clarity, not technical complexity

Chart Selection Guide:

• Trends over time: Line chart
• Comparisons: Horizontal bar chart
• Proportions: Pie/donut chart
• Distributions: Histogram, box plot
• Correlations: Scatter plot, heatmap
• Rankings: Horizontal bar chart
• Part-to-whole: Stacked bar, treemap

For complete guidelines: See references/visualization_guidelines.md

Workflow 3: Identifying Data Gaps

When current data cannot support requested insight:

1. Identify gap type - Missing granularity, dimensions, metrics, time windows, or customer data
2. Document current data - What we have
3. Document what's needed - Specific columns, models, or features
4. Recommend solution - Schema additions, new features, new models
5. Estimate timeline - Implementation effort
6. Provide alternative - What can be done with current data

Gap Types:

• Missing Granularity: Daily only, need hourly
• Missing Dimensions: No product categories
• Missing Metrics: No profit margins
• Missing Time Windows: No year-over-year data
• Missing Customer Data: Anonymous transactions

For complete guide: See references/data_gaps_guide.md

Response Template:

⚠️ Data Gap Identified

Requested Insight: [What they want]
Current Data: [What we have]
Missing: [What's needed]

Recommendation to enable this insight:
1. Add to schema: [column additions]
2. Create features: [new functions]
3. Add model: [new aggregation]
4. Expected timeline: [implementation time]

Alternative: [What can be done with current data instead]

Workflow 4: Creating Actionable Recommendations

Every insight must include actionable recommendations:

1. State the insight - What the data shows
2. Explain the impact - Why it matters (revenue, efficiency, risk)
3. Specify the action - What the business should do
4. Assign priority - High/Medium/Low
5. Define timeline - When to act (immediate, 1-4 weeks, 1-3 months)

Example:

Insight: 35% of revenue comes from just 8 products (Pareto principle)
Impact: Inventory focus opportunity - CLP $2.5M concentrated in 8 SKUs
Action: Ensure these 8 products never go out of stock; negotiate better supplier terms
Priority: HIGH
Timeline: Immediate - implement stock alerts this week

For complete framework: See references/recommendations_framework.md

Business Intelligence Patterns

Pattern 1: Revenue Health Dashboard

• Metrics: Total revenue, growth %, avg ticket trend, top 10 products, day-of-week heatmap
• Charts: KPI cards, line chart (trend), horizontal bar (products), heatmap (patterns)

Pattern 2: Customer Behavior Analysis

• Metrics: New vs returning, retention rate, purchase frequency, segmentation, churn risk
• Charts: Stacked area (segments), scatter plot (frequency vs spend), cohort retention matrix

Pattern 3: Product Performance Matrix

• Metrics: Sales velocity, revenue contribution, stock turnover, days since last sale
• Charts: Scatter plot (velocity vs revenue), Pareto chart, matrix (quadrants)

Pattern 4: Operational Insights

• Metrics: Peak hours, staff efficiency, transaction processing time, payment preferences
• Charts: Hourly heatmap, day-of-week bar chart, payment method pie chart

For complete patterns with examples: See references/bi_patterns.md

Statistical Analysis Techniques

Descriptive Statistics: Mean, median, mode, standard deviation, percentiles, quartiles

Trend Analysis: Moving averages (7-day, 30-day), growth rates (MoM, YoY), seasonality decomposition, trend lines

Segmentation: RFM analysis, K-means clustering, Pareto/ABC analysis, quartile segmentation

Forecasting (Basic): Simple moving average, exponential smoothing, linear trend projection, growth rate extrapolation

For detailed techniques with code examples: See references/statistical_methods.md

Tools and Libraries

Data Manipulation:

• pandas - DataFrames, aggregations, groupby
• numpy - Numerical operations, statistics

Visualization:

• matplotlib - Base plotting library
• seaborn - Statistical visualizations, beautiful defaults
• plotly - Interactive charts (optional)

Statistics:

• scipy.stats - Statistical tests, distributions
• sklearn - Clustering, segmentation (optional)

Export:

• openpyxl - Excel writing (if needed)
• matplotlib.pyplot.savefig() - Save charts as PNG/PDF

Best Practices

1. Always start with data validation - Check quality before analysis
2. Use descriptive variable names - total_revenue not tr
3. Add markdown cells - Explain each analysis section
4. Include chart titles and labels - Make charts self-explanatory
5. Format numbers for business - Use , separators and currency symbols
6. Highlight key findings - Use annotations, bold text, colors
7. Provide context - Compare to previous periods, benchmarks, goals
8. End with actions - Every insight needs a recommendation
9. Save outputs - Export charts and summary tables
10. Document assumptions - Note any data limitations or caveats

Executive Communication Guidelines

For Business Owners (Non-Technical):

• Use plain language (avoid technical jargon)
• Lead with impact (revenue, profit, savings)
• Use currency and percentages (not raw counts)
• Prioritize actionable insights
• Include visual dashboards
• Limit to 5-7 key recommendations

Report Structure:

1. Executive Summary (1-2 paragraphs)
2. Key Metrics (3-5 KPIs with visual cards)
3. Main Insights (3-5 findings with charts)
4. Recommendations (5-7 prioritized actions)
5. Appendix (detailed tables, methodology)

For complete guidelines: See references/executive_communication.md

Integration with Other Skills

From Business Skill

• Receive: User personas, use cases, business requirements
• Provide: Insights notebooks tailored to persona needs, recommendations aligned with business goals
• Example: Business defines "Operations Manager" persona → Insights creates staffing optimization notebook

From Architect Skill

• Receive: Available features, data schema, execution capabilities
• Provide: Notebook requirements, visualization needs, new metric requests
• Example: Architect implements RFM model → Insights creates customer segmentation analysis

To Marketing Skill

• Provide: Data-driven insights, customer segments, product performance metrics
• Receive: Communication requirements, target audience for reports
• Example: Insights finds VIP segment → Marketing creates retention campaign

To Executive Skill

• Provide: Business intelligence reports, data gap assessments, implementation recommendations
• Receive: Strategic priorities, reporting requirements, timeline constraints
• Example: Executive requests Chilean market analysis → Insights creates localized dashboard

Working Directory

Insights Workspace: .claude/skills/insights/

Bundled Resources:

• references/visualization_guidelines.md - Chart selection, design principles
• references/bi_patterns.md - 4 common BI patterns with examples
• references/statistical_methods.md - Descriptive stats, trend analysis, segmentation, forecasting
• references/recommendations_framework.md - 5-component actionable recommendations
• references/data_gaps_guide.md - 5 gap types with response templates
• references/executive_communication.md - Non-technical reporting guidelines
• assets/templates/notebook_template.md - Standard 5-section insights notebook structure

Context Workspace: /ai/insights/

• Analysis prototypes, data exploration, notebook drafts
• Existing files: notebook_standards.md, dynamic_calculations_inventory.md, placeholder_static_content.md

Production Notebooks: /notebooks/

• Final notebook implementations
• Organized by persona and use case

Living Documents (Append Only):

• /ai/CHANGELOG.md - When insights lead to code improvements
• /ai/FEATURE_IMPLEMENTATIONS.md - When new analytical features are added
• /ai/guides/NOTEBOOK_IMPROVEMENTS.md - Notebook refactoring and enhancements

Context Folders (Reference as Needed):

• /ai/business/ - User personas and use cases (target audience for notebooks)
• /ai/specs/model/ - Model specifications and technical details

Common Insight Requests

"Show me which products are most profitable"

Assessment: Requires product revenue and costs Check: Does product_daily_export.xlsx have cost_total_sum? If NO: Recommend adding cost data to schema + margin attributes If YES: Calculate profit, margin_pct, visualize top 10

"Identify customer churn risks"

Assessment: Requires customer transaction history, recency, frequency Check: Does customer_profile_export.xlsx exist with RFM metrics? If NO: Recommend creating customer_profile model with recency calculations If YES: Segment customers by recency/frequency, identify at-risk

"When should I hire more staff?"

Assessment: Requires hourly transaction patterns, day-of-week patterns Check: Does daily_hour_export.xlsx exist? If YES: Analyze peak hours and days for staffing recommendations

"Forecast next month's revenue"

Assessment: Requires historical daily/weekly revenue, trend analysis Check: At least 3 months of historical data in daily_export.xlsx? If YES: Use time series techniques for basic forecasting

Remember

• Create insights, not features - Use architect skill for model development
• Always validate data first - Don't analyze garbage data
• Business language - Speak in revenue, savings, efficiency
• Visual + Textual - Combine charts with written recommendations
• Actionable - Every insight needs a "what to do about it"
• Identify gaps - Tell users what's missing and how to add it
• Use examples - Show actual code, not just descriptions
• Think executive - What would a CEO want to know?

Version History

v2.0.0 (2025-10-30)

• Refactored to use progressive disclosure pattern
• Extracted detailed content to references/ (6 files) and assets/templates/ (1 file)
• Converted to imperative form (removed second-person voice)
• Reduced from 587 lines to ~295 lines
• Added clear workflow sections
• Enhanced data gap identification process

v1.0.0 (2025-10-28)

• Initial version with comprehensive insights guidance

---

Last Updated: 2025-10-30 Core Focus: Transform data into actionable business intelligence Key Principle: Every insight must have a specific, actionable recommendation