@axiom-lattice/examples-deep_research 1.0.26 → 1.0.28

package/src/agents/data_agent/skills/business-analytics/reference.md

@@ -0,0 +1,240 @@
+# Business Analytics Reference Documentation
+
+## Detailed Methodology
+
+### 1. Gross Margin Calculation (JournalEntry口径)
+
+#### Data Source
+- **Primary Table**: `MTC_VW_AI_JournalEntry`
+- **Revenue Accounts**: All accounts starting with `4` (e.g., 401020100 for candy revenue)
+- **COGS Accounts**: All accounts starting with `5` (e.g., 501030100 for candy COGS)
+
+#### Formulas
+```
+Net Revenue = SUM(Credit - Debit) WHERE AccountCode LIKE '4%'
+Net COGS = SUM(Credit - Debit) WHERE AccountCode LIKE '5%'
+Gross Margin = Net Revenue + Net COGS
+Gross Margin % = (Gross Margin / Net Revenue) × 100
+```
+
+#### Channel Splitting
+Use `PrcName` (CC1 Business Unit) and `PrcName2` (CC2 Channel) dimensions:
+```sql
+SELECT 
+  PrcName2 as Channel,
+  SUM(CASE WHEN AccountCode LIKE '4%' THEN Credit - Debit ELSE 0 END) as Revenue,
+  SUM(CASE WHEN AccountCode LIKE '5%' THEN Credit - Debit ELSE 0 END) as COGS
+FROM MTC_VW_AI_JournalEntry
+WHERE AccountCode IN ('401020100', '501030100')
+GROUP BY PrcName2
+```
+
+### 2. Profit Bridge Calculation
+
+#### Revenue Foundation
+- **Source**: `OINV` (A/R Invoice) net amounts
+- **Period**: Analysis period dates
+- **Formula**: `SUM(DocTotal - VatSum)` for candy-related items
+
+#### COGS Components
+```
+Historical COGS = From JournalEntry (Account 501030100)
+```
+
+#### Operating Expenses
+```
+Trading Terms = Sum of promotional discounts from OINV line items
+Carriage Outwards = Delivery costs from OPCH or dedicated expense accounts
+Sales Discount = General discount from OINV
+Expired Stock = Write-offs from inventory adjustment journal entries
+Nestle Subsidy = Commission income from dedicated revenue accounts
+```
+
+#### Risk Adjustments
+```
+Bad Debt Provision = AR >180 days × 50% estimated loss rate
+Inventory Carrying Cost = Average Inventory × 8% cost of capital
+```
+
+### 3. Cash Conversion Cycle (CCC)
+
+#### DIO (Days Inventory Outstanding)
+```
+Average Inventory = (Beginning Inventory + Ending Inventory) / 2
+DIO = (Average Inventory / COGS) × 365
+
+Where:
+- Inventory = From BATCHSTOCK or STOCK tables
+- COGS = From JournalEntry (annual)
+```
+
+#### DSO (Days Sales Outstanding)
+```
+DSO = (Accounts Receivable / Revenue) × 365
+
+Where:
+- AR = From CUSTBAL or OINV open items
+- Revenue = From JournalEntry or OINV (annual)
+```
+
+#### DPO (Days Payable Outstanding)
+```
+DPO = (Accounts Payable / COGS) × 365
+
+Where:
+- AP = From vendor balance or OPCH open items
+```
+
+#### CCC Formula
+```
+CCC = DIO + DSO - DPO
+```
+
+**Interpretation:**
+- < 60 days: Excellent working capital management
+- 60-100 days: Good/Industry average
+- 100-150 days: Needs improvement
+- > 150 days: Critical working capital issues
+
+### 4. GMROI (Gross Margin Return on Inventory Investment)
+
+#### Formula
+```
+GMROI = Annual Gross Margin / Average Inventory
+```
+
+#### Calculation
+```
+Annual Gross Margin = From JournalEntry (12-month rolling)
+Average Inventory = (Beginning + Ending) / 2 from STOCK table
+
+Example:
+GMROI = ¥3,735,750 / ¥1,337,863 = 2.79x
+```
+
+#### Benchmarks by Industry
+
+| Industry | GMROI Range | Interpretation |
+|----------|-------------|----------------|
+| FMCG/Distribution | 3.0–5.0x | Healthy inventory turns |
+| Retail (General) | 2.0–4.0x | Acceptable range |
+| Luxury Goods | 1.5–3.0x | Lower turns, higher margins |
+| Grocery/Supermarket | 4.0–8.0x | High volume, thin margins |
+
+#### Analysis
+```
+Current: 2.79x
+Benchmark: 3.0–5.0x
+Gap: -0.21x to -2.21x
+
+Root Causes:
+1. Slow-moving SKUs (KitKat, Kopiko overstock)
+2. Near-expiry write-off risk
+3. High-value inventory (Ferrero) with slow turns
+```
+
+### 5. Strategic Scenario Modeling
+
+#### Scenario Comparison Framework
+
+```
+                    Option A: Cut Local    Option B: Expand Export
+                    ───────────────────    ───────────────────────
+Revenue             ¥17.0M                  ¥24.7M
+Gross Margin        ¥3.3M                   ¥5.3M
+Operating Profit    ¥1.9M                   ¥2.9M
+Profit Margin       11.1%                   11.7%
+
+Key Differences:
+- Revenue Impact: +¥7.7M (45% increase)
+- Margin Improvement: +¥2.0M (60% increase)
+- Operating Leverage: 1.5x
+```
+
+#### Business Model Characteristics Matrix
+
+```
+                    Export Distribution    Local FMCG
+                    ───────────────────    ───────────
+Customer Count      8–42                   200–300+
+Avg Invoice         ¥51K–63K               ¥2.5K–8K
+Unit Margin         94–97%*                77–97%*
+Abs Margin/Unit     ¥115–260               ¥15–85
+Delivery Cost       Low                    High
+TT Share            High                   Medium
+AR Period           256 days               30–60 days
+Bad Debt Risk       Extreme                Minimal
+Subsidy Dependency  High                   Medium
+Cash Recovery       Poor                   Good
+
+* Margin口径存疑 - see §1.5
+```
+
+### 6. Data Quality & Methodology Alerts
+
+#### ⚠️ Critical Data Quality Issues
+
+**1. Inventory Unit of Measure Discrepancy**
+```
+Suspected Issue: Case vs Piece confusion in system
+Evidence:
+- KitKat 2F 17g: System shows 703,848 units
+- At current sales velocity: 131 years to sell
+- Likely actual: 703,848 ÷ [units per case] = realistic quantity
+
+Action Required: Immediate physical count verification
+Risk: Material misstatement of inventory assets
+```
+
+**2. Cost/Pricing口径 Inconsistency**
+```
+Issue: SKU-level margin calculations using STOCK.AvgPrice vs OINV.Price
+- May double-count or misallocate costs
+- SKU-level 77–99% margins not reliable
+
+Resolution: All margin analysis in this report uses JournalEntry口径 only
+```
+
+**3. Accounts Receivable Aging Reliability**
+```
+Note: 256-day DSO may include:
+- Disputed invoices
+- Unapplied payments
+- System timing differences
+
+Recommendation: Perform detailed AR aging analysis by customer before provisioning
+```
+
+### 7. Report Validation Checklist
+
+Before finalizing any business analytics report, verify:
+
+#### Data Quality
+- [ ] All metrics have documented sources
+- [ ] Calculations are transparent and reproducible
+- [ ] Data anomalies are flagged and explained
+- [ ] Time periods are consistently defined
+
+#### Analysis Rigor
+- [ ] Methodology limitations are disclosed
+- [ ] Multiple scenarios are considered
+- [ ] Risks are quantified where possible
+- [ ] Benchmarks are appropriately sourced
+
+#### Actionability
+- [ ] Executive summary leads with conclusions
+- [ ] Top actions are prioritized
+- [ ] Roadmap has clear owners and timelines
+- [ ] Next steps are specific and measurable
+
+#### Presentation
+- [ ] Tables are formatted consistently
+- [ ] ASCII charts use appropriate scaling
+- [ ] Language is professional and concise
+- [ ] Report is proofread for errors
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: 2026-03-03  
+**Maintainer**: Business Analytics Skill

package/src/agents/data_agent/skills/business-analytics/resources/data/sample.json

@@ -0,0 +1,66 @@
+{
+  "report_metadata": {
+    "title": "Candy Business Analysis",
+    "data_source": "ZZZZ_KAIMAYMTC_TEST",
+    "analysis_period": "2025-01-01 to 2025-12-31",
+    "report_date": "2026-03-03",
+    "version": "v2.1"
+  },
+  "financial_summary": {
+    "revenue": 19228590,
+    "cogs": -15492840,
+    "gross_profit": 3735750,
+    "gross_margin_pct": 19.4,
+    "operating_expenses": {
+      "trading_terms": -502145,
+      "carriage_outwards": -420798,
+      "sales_discount": -192784,
+      "expired_stock": -122889,
+      "nestle_subsidy": 1829032
+    },
+    "commercial_profit": 4326166,
+    "risk_adjustments": {
+      "bad_debt_provision": -2175000,
+      "inventory_carrying_cost": -107000
+    },
+    "real_operating_profit": 2044166,
+    "operating_margin_pct": 10.6
+  },
+  "cash_conversion_cycle": {
+    "dio_days": 31,
+    "dso_days": 256,
+    "dpo_days": 27,
+    "ccc_days": 260
+  },
+  "gmroi": {
+    "annual_gross_margin": 3735750,
+    "average_inventory": 1337863,
+    "gmroi": 2.79,
+    "benchmark_range": "3.0-5.0x"
+  },
+  "ar_aging": {
+    "total_ar": 10200000,
+    "buckets": [
+      {"range": "0-30 days", "amount": 700000, "pct": 7},
+      {"range": "31-90 days", "amount": 3500000, "pct": 35},
+      {"range": "91-180 days", "amount": 1000000, "pct": 10},
+      {"range": "181-365 days", "amount": 900000, "pct": 9},
+      {"range": "1-2 years", "amount": 600000, "pct": 6},
+      {"range": ">2 years", "amount": 2900000, "pct": 28}
+    ]
+  },
+  "scenarios": {
+    "cut_local": {
+      "revenue": 17033590,
+      "gross_profit": 3296000,
+      "operating_profit": 1890000,
+      "margin_pct": 11.1
+    },
+    "expand_export": {
+      "revenue": 24719385,
+      "gross_profit": 5257000,
+      "operating_profit": 2890000,
+      "margin_pct": 11.7
+    }
+  }
+}

package/src/agents/data_agent/skills/business-analytics/resources/prompts/analyze.txt

@@ -0,0 +1,128 @@
+# Business Analytics Analysis Prompt
+
+You are a senior financial analyst and CFO advisor. Your task is to analyze business metrics data and generate a comprehensive, board-level business analysis report following the structure and style demonstrated in the skill examples.
+
+## Input Data
+
+You will receive:
+1. Business metrics data (JSON, CSV, or database query results)
+2. Analysis period dates
+3. Business context (industry, company name, data sources)
+
+## Report Requirements
+
+Generate a complete business analysis report with the following sections:
+
+### 1. Executive Summary (1 Page)
+- 3-5 core conclusions with specific metrics
+- Top 3 immediate actions with timelines and expected impact
+
+### 2. Model 1: Gross Margin & Channel Analysis
+- Methodology explanation with data sources
+- Summary financial tables
+- Channel/customer segment breakdowns
+
+### 3. Model 2: Profit Bridge
+- Complete profit flow from revenue to operating profit
+- ASCII table format showing all line items
+- Risk adjustment calculations
+- Key insight callouts with visual bar charts
+
+### 4. Model 3: Cash Conversion Cycle + GMROI
+- DIO, DSO, DPO calculations with formulas
+- DSO aging breakdown with ASCII bar charts
+- GMROI calculation vs industry benchmarks
+- CCC optimization recommendations
+
+### 5. Model 4: Strategic Scenarios
+- 2-3 scenario comparisons with P&L impact
+- Business model characteristics matrix
+- Strategic trade-off analysis
+
+### 6. Model 5: Executive Q&A
+- 5 CFO questions with data-driven answers
+- 5 CEO questions with strategic analysis
+
+### 7. Action Roadmap
+- Priority matrix (Impact vs Urgency)
+- Immediate/Short-term/Medium-term action tables
+- Owner and deadline assignments
+
+### 8. Appendix
+- Key financial metrics quick reference table
+- Data sources and methodology notes
+
+## Writing Style Guidelines
+
+### Tone & Language
+- Professional, board-level language
+- Direct and concise
+- Data-driven with clear sourcing
+- Action-oriented
+
+### Formatting Standards
+- Use ASCII tables for all data presentation
+- Include currency symbols (¥, $, €, SGD) consistently
+- Show percentages with 1 decimal place
+- Use █ characters for visual bar charts
+- Separate sections with `---` horizontal rules
+
+### Data Presentation
+- Always cite data sources
+- Include analysis period dates
+- Show calculations transparently
+- Flag methodology limitations with ⚠️ alerts
+
+### Key Metrics to Always Include
+- Revenue and growth rates
+- Gross margin and gross profit
+- Operating profit and margin
+- Cash conversion cycle (DIO, DSO, DPO)
+- GMROI with industry benchmark
+- Key risk metrics (bad debt, inventory aging)
+
+## Output Format
+
+Generate the complete report in markdown format following this exact structure:
+
+```markdown
+# [Business Unit] [Product/Service] Analysis Report
+## [Subtitle/Context]
+
+**Data Source**: [Source]  
+**Analysis Period**: [Dates]  
+**Report Date**: [Date]  
+**Version**: [Version]
+
+---
+
+## Executive Summary
+...
+
+---
+
+## Model 1: [Dimension]
+...
+
+---
+
+[Continue with all sections...]
+
+---
+
+## Appendix
+...
+```
+
+## Quality Checklist
+
+Before finalizing, verify:
+- [ ] All sections are complete with data
+- [ ] Calculations are mathematically correct
+- [ ] Tables are properly formatted
+- [ ] No placeholder text remains
+- [ ] Executive summary accurately reflects detailed findings
+- [ ] Action items are specific and assignable
+- [ ] All metrics have proper units and context
+
+Now analyze the provided data and generate the complete business analysis report following these guidelines.

package/src/agents/data_agent/skills/business-analytics/resources/templates/report-template.md

@@ -0,0 +1,260 @@
+# Business Analysis Report Template
+
+## Metadata
+- **Report Title**: [Business Unit] [Product/Service] Analysis Report
+- **Data Source**: [Database/Table Names]
+- **Analysis Period**: [Start Date] to [End Date]
+- **Report Date**: [Generation Date]
+- **Version**: [Version Number]
+
+---
+
+## Executive Summary (1 Page)
+
+### Core Conclusions
+
+1. **[Key Finding 1]** — [Metric and impact]
+2. **[Key Finding 2]** — [Metric and impact]
+3. **[Key Finding 3]** — [Metric and impact]
+
+### Top 3 Immediate Actions
+
+1. **[Action 1]** — [Timeline and expected impact]
+2. **[Action 2]** — [Timeline and expected impact]
+3. **[Action 3]** — [Timeline and expected impact]
+
+---
+
+## Model 1: [Analysis Dimension 1]
+
+### 1.1 Methodology
+
+[Explain data sources, calculations, and any limitations]
+
+### 1.2 Summary Data
+
+| Metric | Value | Unit |
+|--------|-------|------|
+| [Metric 1] | [Value] | [Unit] |
+| [Metric 2] | [Value] | [Unit] |
+| [Metric 3] | [Value] | [Unit] |
+
+### 1.3 Breakdown by [Dimension]
+
+| [Dimension] | [Metric 1] | [Metric 2] | [Metric 3] |
+|-------------|------------|------------|------------|
+| [Category 1] | [Value] | [Value] | [Value] |
+| [Category 2] | [Value] | [Value] | [Value] |
+| [Category 3] | [Value] | [Value] | [Value] |
+
+---
+
+## Model 2: Profit Bridge Analysis
+
+```
+                                          [Currency]     % of Revenue
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Revenue                                          [Amount]       100.0%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Less: Cost of Goods Sold                         [Amount]        [Pct]%
+                                                 ─────────   ─────────
+Gross Profit                                     [Amount]        [Pct]%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Less: [Operating Expense 1]                       [Amount]        [Pct]%
+Less: [Operating Expense 2]                       [Amount]        [Pct]%
+Plus: [Other Income 1]                            [Amount]        [Pct]%
+                                                 ─────────   ─────────
+Commercial Profit                                [Amount]        [Pct]%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Less: [Risk Adjustment 1]                         [Amount]        [Pct]%
+Less: [Risk Adjustment 2]                         [Amount]        [Pct]%
+                                                 ─────────   ─────────
+Real Operating Profit                            [Amount]        [Pct]%
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Key Insights
+
+- **[Insight 1]**: [Description and impact]
+- **[Insight 2]**: [Description and impact]
+- **[Insight 3]**: [Description and impact]
+
+---
+
+## Model 3: Cash Conversion Cycle + GMROI
+
+### 3.1 CCC Components
+
+| Metric | Days | Formula | Calculation |
+|--------|------|---------|-------------|
+| DIO (Days Inventory Outstanding) | [Days] | (Avg Inventory / COGS) × 365 | [Show work] |
+| DSO (Days Sales Outstanding) | [Days] | (AR / Revenue) × 365 | [Show work] |
+| DPO (Days Payable Outstanding) | [Days] | (AP / COGS) × 365 | [Show work] |
+| **Cash Conversion Cycle** | **[Days]** | **DIO + DSO - DPO** | **[Result]** |
+
+### 3.2 DSO Structure Breakdown
+
+```
+Accounts Receivable Distribution:
+  [Bucket 1]:   [Amount]   [Pct]%   [Visual Bar]
+  [Bucket 2]:   [Amount]   [Pct]%   [Visual Bar]
+  [Bucket 3]:   [Amount]   [Pct]%   [Visual Bar]
+  ...
+  [Bucket N]:   [Amount]   [Pct]%   [Visual Bar]  ← Main Problem
+```
+
+### 3.3 GMROI Analysis
+
+| Metric | Value | Benchmark |
+|--------|-------|-----------|
+| Annual Gross Margin | [Amount] | — |
+| Average Inventory | [Amount] | — |
+| **GMROI** | **[Ratio]x** | [Benchmark Range] |
+
+**Interpretation**: [Analysis of GMROI vs benchmark]
+
+### 3.4 CCC Optimization Opportunities
+
+| Initiative | Impact on CCC | Priority | Implementation |
+|------------|---------------|----------|----------------|
+| [Initiative 1] | [Days] | [Priority] | [Action] |
+| [Initiative 2] | [Days] | [Priority] | [Action] |
+| [Initiative 3] | [Days] | [Priority] | [Action] |
+
+---
+
+## Model 4: Strategic Scenario Analysis
+
+### 4.1 Scenario Comparison
+
+| Metric | [Scenario A] | [Scenario B] | [Scenario C] | Delta (B-A) |
+|--------|--------------|--------------|--------------|-------------|
+| Revenue | [Amount] | [Amount] | [Amount] | +[Amount] |
+| Gross Margin | [Amount] | [Amount] | [Amount] | +[Amount] |
+| Operating Profit | [Amount] | [Amount] | [Amount] | +[Amount] |
+| Profit Margin | [Pct]% | [Pct]% | [Pct]% | +[Pct]% |
+
+### 4.2 Business Model Characteristics
+
+| Characteristic | [Model A] | [Model B] |
+|----------------|-----------|-----------|
+| [Attribute 1] | [Value] | [Value] |
+| [Attribute 2] | [Value] | [Value] |
+| [Attribute 3] | [Value] | [Value] |
+| [Attribute 4] | [Value] | [Value] |
+| [Attribute 5] | [Value] | [Value] |
+
+**Core Trade-off**: [Description of strategic choice]
+
+---
+
+## Model 5: Executive Q&A
+
+### CFO Questions
+
+**Q1: [Financial question]?**
+
+[Data-driven answer with supporting analysis]
+
+**Q2: [Risk question]?**
+
+[Data-driven answer with supporting analysis]
+
+**Q3: [Liquidity question]?**
+
+[Data-driven answer with supporting analysis]
+
+**Q4: [Operational question]?**
+
+[Data-driven answer with supporting analysis]
+
+**Q5: [Strategic financial question]?**
+
+[Data-driven answer with supporting analysis]
+
+### CEO Questions
+
+**Q1: [Strategic direction question]?**
+
+[Strategic analysis and recommendation]
+
+**Q2: [Talent/Organization question]?**
+
+[Strategic analysis and recommendation]
+
+**Q3: [Market/Product question]?**
+
+[Strategic analysis and recommendation]
+
+**Q4: [Growth question]?**
+
+[Strategic analysis and recommendation]
+
+**Q5: [Long-term sustainability question]?**
+
+[Strategic analysis and recommendation]
+
+---
+
+## Action Roadmap
+
+### Priority Matrix
+
+```
+Impact
+  High │  [Action 2]            [Action 1]
+       │  (Urgent/High)          (High/Plannable)
+       │
+       │  [Action 3]            [Action 4]
+  Mid  │  (Urgent/Mid)           (Plannable/Mid)
+       │
+       │  [Action 5]            [Action 6]
+  Low  │  (Urgent/Low)           (Plannable/Low)
+       └────────────────────────────────────────
+              Urgent                  Plannable
+```
+
+### Immediate Actions (This Week)
+
+| Action | Owner | Deadline | Expected Impact |
+|--------|-------|----------|-----------------|
+| [Action 1] | [Owner] | [Date] | [Impact] |
+| [Action 2] | [Owner] | [Date] | [Impact] |
+
+### Short-term Actions (This Month)
+
+| Action | Owner | Deadline | Expected Impact |
+|--------|-------|----------|-----------------|
+| [Action 1] | [Owner] | [Date] | [Impact] |
+| [Action 2] | [Owner] | [Date] | [Impact] |
+
+### Medium-term Actions (This Quarter)
+
+| Action | Owner | Deadline | Expected Impact |
+|--------|-------|----------|-----------------|
+| [Action 1] | [Owner] | [Date] | [Impact] |
+| [Action 2] | [Owner] | [Date] | [Impact] |
+
+---
+
+## Appendix: Key Financial Metrics Quick Reference
+
+| Metric | Formula | Industry Benchmark | Current Value |
+|--------|---------|-------------------|---------------|
+| Gross Margin % | (Revenue - COGS) / Revenue | 15-25% | [Value] |
+| Operating Margin % | Operating Profit / Revenue | 8-15% | [Value] |
+| Net Margin % | Net Profit / Revenue | 5-10% | [Value] |
+| DSO (Days Sales Outstanding) | (AR / Revenue) × 365 | 30-60 days | [Value] |
+| DIO (Days Inventory Outstanding) | (Inventory / COGS) × 365 | 20-40 days | [Value] |
+| DPO (Days Payable Outstanding) | (AP / COGS) × 365 | 30-60 days | [Value] |
+| CCC (Cash Conversion Cycle) | DIO + DSO - DPO | 60-100 days | [Value] |
+| GMROI | Gross Margin / Average Inventory | 3.0-5.0x | [Value] |
+| Inventory Turnover | COGS / Average Inventory | 6-12x | [Value] |
+| Current Ratio | Current Assets / Current Liabilities | 1.2-2.0x | [Value] |
+| Quick Ratio | (Current Assets - Inventory) / Current Liabilities | 0.8-1.5x | [Value] |
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: 2026-03-03  
+**Maintainer**: Business Analytics Skill