# Insight Report Template
# Standardized template for generating analytical insights and reports across the AI Agentic Data Stack Framework

metadata:
  template_id: "insight-report-tmpl"
  name: "Insight Report Template"
  version: "1.0.0"
  description: "Comprehensive template for creating analytical insight reports with structured findings, recommendations, and actionable intelligence"
  category: "analytics-reporting"
  tags: ["insights", "analysis", "reporting", "recommendations", "intelligence", "findings"]
  created_by: "AI Agentic Data Stack Framework"
  created_date: "2025-01-23"

template:
  name: "Insight Report Template"
  description: "Template for creating analytical insight reports with structured findings"
  version: "1.0.0"

# Report Configuration
report_config:
  # Basic Information
  report_id: "${report_id}"
  title: "${report_title}"
  subtitle: "${report_subtitle}"
  executive_summary: "${executive_summary}"
  
  # Report Classification
  classification:
    type: "${report_type}" # strategic, operational, tactical, exploratory, compliance
    urgency: "${urgency_level}" # high, medium, low
    confidentiality: "${confidentiality_level}" # public, internal, confidential, restricted
    
  # Metadata
  metadata:
    author: "${report_author}"
    department: "${author_department}"
    creation_date: "${creation_date}"
    reporting_period: "${reporting_period}"
    data_as_of_date: "${data_as_of_date}"
    
  # Distribution
  distribution:
    primary_audience: ["${primary_audience}"]
    secondary_audience: ["${secondary_audience}"]
    stakeholder_groups: ["${stakeholder_groups}"]

# Analysis Context
analysis_context:
  # Business Context
  business_context:
    objective: "${analysis_objective}"
    business_question: "${business_question}"
    hypothesis: "${analysis_hypothesis}"
    success_criteria: ["${success_criteria}"]
    
  # Analytical Scope
  scope:
    time_frame: "${analysis_time_frame}"
    geographic_scope: "${geographic_scope}"
    business_units: ["${business_units}"]
    product_lines: ["${product_lines}"]
    customer_segments: ["${customer_segments}"]
    
  # Methodology
  methodology:
    analytical_approach: "${analytical_approach}" # descriptive, diagnostic, predictive, prescriptive
    data_sources: ["${data_sources}"]
    analytical_techniques: ["${analytical_techniques}"]
    tools_used: ["${tools_used}"]
    
  # Limitations and Assumptions
  limitations:
    data_limitations: ["${data_limitations}"]
    methodological_limitations: ["${methodological_limitations}"]
    assumptions: ["${key_assumptions}"]

# Data Foundation
data_foundation:
  # Data Sources
  data_sources:
    - source_id: "${source_id}"
      name: "${source_name}"
      type: "${source_type}" # database, api, file, survey, external
      description: "${source_description}"
      data_quality_score: ${data_quality_score}
      freshness: "${data_freshness}"
      completeness: ${data_completeness_percent}
      
  # Data Processing
  data_processing:
    cleaning_procedures: ["${cleaning_procedures}"]
    transformation_steps: ["${transformation_steps}"]
    validation_checks: ["${validation_checks}"]
    quality_issues: ["${quality_issues}"]
    
  # Sample Characteristics
  sample:
    total_records: ${total_records}
    time_period: "${sample_time_period}"
    sampling_method: "${sampling_method}"
    representativeness: "${representativeness_assessment}"

# Key Findings Structure
key_findings:
  # Primary Insights
  primary_insights:
    - insight_id: "${insight_id}"
      category: "${insight_category}"
      finding: "${key_finding}"
      significance: "${statistical_significance}"
      confidence_level: ${confidence_level}
      impact_assessment: "${impact_assessment}" # high, medium, low
      
      # Supporting Evidence
      evidence:
        statistical_measures: ["${statistical_measures}"]
        visualizations: ["${supporting_charts}"]
        data_points: ["${key_data_points}"]
        
      # Business Implications
      implications:
        immediate_impact: "${immediate_impact}"
        long_term_implications: "${long_term_implications}"
        affected_stakeholders: ["${affected_stakeholders}"]
        
  # Secondary Findings
  secondary_insights:
    - insight_id: "${secondary_insight_id}"
      finding: "${secondary_finding}"
      context: "${finding_context}"
      relevance: "${business_relevance}"
      
  # Trend Analysis
  trends:
    - trend_id: "${trend_id}"
      trend_description: "${trend_description}"
      trend_direction: "${trend_direction}" # increasing, decreasing, stable, cyclical
      trend_strength: "${trend_strength}" # strong, moderate, weak
      duration: "${trend_duration}"
      drivers: ["${trend_drivers}"]
      
  # Anomalies and Outliers
  anomalies:
    - anomaly_id: "${anomaly_id}"
      description: "${anomaly_description}"
      detected_method: "${detection_method}"
      potential_causes: ["${potential_causes}"]
      investigation_status: "${investigation_status}"

# Analytical Deep Dive
analytical_deep_dive:
  # Quantitative Analysis
  quantitative_analysis:
    # Descriptive Statistics
    descriptive_stats:
      measures_of_center:
        mean: ${mean_value}
        median: ${median_value}
        mode: ${mode_value}
        
      measures_of_spread:
        standard_deviation: ${std_deviation}
        variance: ${variance_value}
        range: ${range_value}
        quartiles: ["${q1}", "${q2}", "${q3}"]
        
    # Comparative Analysis
    comparative_analysis:
      baseline_comparison:
        baseline_period: "${baseline_period}"
        current_vs_baseline: "${comparison_result}"
        percentage_change: ${percentage_change}
        
      benchmark_comparison:
        benchmark_source: "${benchmark_source}"
        performance_vs_benchmark: "${benchmark_comparison}"
        percentile_ranking: ${percentile_ranking}
        
    # Statistical Tests
    statistical_tests:
      - test_name: "${test_name}"
        null_hypothesis: "${null_hypothesis}"
        alternative_hypothesis: "${alternative_hypothesis}"
        test_statistic: ${test_statistic}
        p_value: ${p_value}
        result: "${test_result}" # reject_null, fail_to_reject_null
        
  # Qualitative Analysis
  qualitative_analysis:
    themes_identified: ["${identified_themes}"]
    patterns_observed: ["${observed_patterns}"]
    stakeholder_feedback: ["${stakeholder_feedback}"]
    contextual_factors: ["${contextual_factors}"]

# Visualizations and Evidence
visualizations:
  # Primary Charts
  primary_charts:
    - chart_id: "${chart_id}"
      chart_type: "${chart_type}"
      title: "${chart_title}"
      description: "${chart_description}"
      key_message: "${chart_key_message}"
      data_source: "${chart_data_source}"
      
  # Supporting Graphics
  supporting_graphics:
    - graphic_id: "${graphic_id}"
      type: "${graphic_type}" # table, infographic, diagram, map
      purpose: "${graphic_purpose}"
      location_in_report: "${graphic_location}"
      
  # Interactive Elements
  interactive_elements:
    - element_id: "${element_id}"
      type: "${interactive_type}" # dashboard, filter, drill-down
      functionality: "${element_functionality}"
      access_method: "${access_method}"

# Recommendations and Actions
recommendations:
  # Strategic Recommendations
  strategic_recommendations:
    - recommendation_id: "${rec_id}"
      priority: "${recommendation_priority}" # high, medium, low
      category: "${recommendation_category}"
      recommendation: "${recommendation_text}"
      
      # Implementation Details
      implementation:
        timeframe: "${implementation_timeframe}"
        resources_required: ["${required_resources}"]
        responsible_parties: ["${responsible_parties}"]
        dependencies: ["${implementation_dependencies}"]
        
      # Expected Outcomes
      outcomes:
        expected_impact: "${expected_impact}"
        success_metrics: ["${success_metrics}"]
        risk_factors: ["${risk_factors}"]
        mitigation_strategies: ["${mitigation_strategies}"]
        
  # Operational Actions
  operational_actions:
    - action_id: "${action_id}"
      urgency: "${action_urgency}" # immediate, short-term, long-term
      action_description: "${action_description}"
      owner: "${action_owner}"
      deadline: "${action_deadline}"
      
  # Follow-up Analysis
  follow_up_analysis:
    recommended_studies: ["${recommended_studies}"]
    data_collection_needs: ["${data_collection_needs}"]
    monitoring_requirements: ["${monitoring_requirements}"]

# Risk Assessment
risk_assessment:
  # Identified Risks
  risks:
    - risk_id: "${risk_id}"
      risk_description: "${risk_description}"
      probability: "${risk_probability}" # high, medium, low
      impact: "${risk_impact}" # high, medium, low
      risk_level: "${overall_risk_level}"
      
      # Risk Management
      mitigation_measures: ["${mitigation_measures}"]
      contingency_plans: ["${contingency_plans}"]
      monitoring_indicators: ["${monitoring_indicators}"]
      
  # Uncertainty Analysis
  uncertainty:
    confidence_intervals: ["${confidence_intervals}"]
    sensitivity_analysis: "${sensitivity_analysis_results}"
    scenario_analysis: ["${scenario_results}"]

# Impact Assessment
impact_assessment:
  # Business Impact
  business_impact:
    financial_impact:
      revenue_impact: "${revenue_impact}"
      cost_impact: "${cost_impact}"
      roi_estimation: "${roi_estimation}"
      
    operational_impact:
      efficiency_gains: ["${efficiency_gains}"]
      process_improvements: ["${process_improvements}"]
      capability_enhancements: ["${capability_enhancements}"]
      
    strategic_impact:
      competitive_advantage: "${competitive_advantage}"
      market_position: "${market_position_impact}"
      strategic_alignment: "${strategic_alignment}"
      
  # Stakeholder Impact
  stakeholder_impact:
    - stakeholder_group: "${stakeholder_group}"
      impact_type: "${impact_type}" # positive, negative, neutral
      impact_description: "${impact_description}"
      engagement_requirements: ["${engagement_requirements}"]

# Quality Assurance
quality_assurance:
  # Validation Checks
  validation:
    data_validation: "${data_validation_status}"
    methodology_review: "${methodology_review_status}"
    peer_review: "${peer_review_status}"
    stakeholder_validation: "${stakeholder_validation_status}"
    
  # Accuracy Assessment
  accuracy:
    fact_checking: "${fact_checking_status}"
    calculation_verification: "${calculation_verification}"
    source_verification: "${source_verification}"
    
  # Completeness Check
  completeness:
    all_questions_addressed: ${all_questions_addressed}
    comprehensive_analysis: ${comprehensive_analysis}
    adequate_evidence: ${adequate_evidence}

# Report Presentation
presentation:
  # Format Options
  format:
    primary_format: "${primary_format}" # pdf, html, presentation, dashboard
    interactive_elements: ${interactive_elements_included}
    mobile_optimized: ${mobile_optimized}
    
  # Structure
  structure:
    executive_summary_length: "${exec_summary_length}" # 1-page, 2-page, extended
    detailed_sections: ["${detailed_sections}"]
    appendices: ["${appendices}"]
    
  # Visual Design
  visual_design:
    template: "${report_template}"
    branding: "${branding_applied}"
    color_scheme: "${color_scheme}"
    accessibility_compliant: ${accessibility_compliant}

# Distribution and Follow-up
distribution:
  # Distribution Plan
  plan:
    primary_distribution: ["${primary_recipients}"]
    secondary_distribution: ["${secondary_recipients}"]
    distribution_method: "${distribution_method}" # email, portal, presentation
    
  # Follow-up Activities
  follow_up:
    presentation_scheduled: ${presentation_scheduled}
    q_and_a_session: ${qa_session_planned}
    implementation_tracking: ${implementation_tracking_enabled}
    
  # Feedback Collection
  feedback:
    feedback_mechanism: "${feedback_mechanism}"
    feedback_deadline: "${feedback_deadline}"
    feedback_incorporation: "${feedback_incorporation_process}"

# Compliance and Governance
compliance:
  # Data Governance
  data_governance:
    data_privacy_compliance: ${privacy_compliant}
    data_security_requirements: ["${security_requirements}"]
    retention_policy: "${data_retention_policy}"
    
  # Regulatory Compliance
  regulatory:
    applicable_regulations: ["${applicable_regulations}"]
    compliance_status: "${compliance_status}"
    audit_trail: "${audit_trail_maintained}"

# Technical Specifications
technical_specs:
  # Tools and Technologies
  tools:
    analytical_tools: ["${analytical_tools}"]
    visualization_tools: ["${visualization_tools}"]
    reporting_platform: "${reporting_platform}"
    
  # Data Processing
  processing:
    compute_resources: "${compute_resources}"
    processing_time: "${processing_time}"
    data_volume: "${data_volume_processed}"
    
  # Integration
  integration:
    data_pipeline: "${data_pipeline_used}"
    automation_level: "${automation_level}"
    refresh_frequency: "${refresh_frequency}"

# Validation Rules
validation_rules:
  required_fields:
    - report_id
    - title
    - executive_summary
    - key_findings
    - recommendations
    
  field_constraints:
    urgency_level:
      allowed_values: ["high", "medium", "low"]
    confidentiality_level:
      allowed_values: ["public", "internal", "confidential", "restricted"]
    report_type:
      allowed_values: ["strategic", "operational", "tactical", "exploratory", "compliance"]
      
  quality_requirements:
    - executive_summary: "max_500_words"
    - confidence_level: ">=0.8"
    - data_quality_score: ">=0.7"

# Report Templates
report_templates:
  executive_summary_report:
    description: "High-level strategic insights for executives"
    max_pages: 3
    focus_areas: ["strategic_implications", "financial_impact", "recommendations"]
    
  detailed_analytical_report:
    description: "Comprehensive analysis for technical stakeholders"
    max_pages: 20
    focus_areas: ["methodology", "detailed_findings", "statistical_analysis", "appendices"]
    
  operational_dashboard_report:
    description: "Real-time operational metrics and insights"
    format: "interactive_dashboard"
    update_frequency: "real-time"
    focus_areas: ["kpis", "trends", "alerts", "drill_down_capability"]

# Usage Examples
examples:
  monthly_sales_analysis:
    report_type: "operational"
    urgency_level: "medium"
    key_findings:
      - finding: "Sales increased 15% month-over-month"
        significance: "statistically_significant"
        confidence_level: 0.95
        
  strategic_market_assessment:
    report_type: "strategic"
    urgency_level: "high"
    recommendations:
      - priority: "high"
        category: "market_expansion"
        timeframe: "3_months"

# Documentation References
documentation:
  reporting_standards: "https://www.icma.org/articles/article/data-driven-performance-reporting"
  statistical_guidelines: "https://www.apa.org/science/leadership/bsa/statistical/"
  visualization_best_practices: "https://storytelling-with-data.com/"
  
# Template Metadata
template_metadata:
  author: "AI Agentic Data Stack Framework"
  maintainer: "Data Analyst"
  last_updated: "2025-01-23"
  changelog:
    - version: "1.0.0"
      date: "2025-01-23"
      changes: "Initial template creation with comprehensive insight reporting structure"

sections:
  - name: "overview"
    description: "Overview and objectives"
    required: true
  - name: "configuration"
    description: "Configuration and setup"
    required: true
  - name: "implementation"
    description: "Implementation details"
    required: true
  - name: "validation"
    description: "Validation and testing"
    required: false