@openfinclaw/findoo-datahub-plugin 2026.3.2 → 2026.3.10

package/_vendor/claude-skills-finance/references/valuation-methodology.md

@@ -0,0 +1,255 @@
+# Valuation Methodology Guide
+
+Comprehensive reference for business valuation approaches including DCF analysis, comparable company analysis, and precedent transactions.
+
+## 1. Discounted Cash Flow (DCF) Methodology
+
+### Overview
+
+DCF is an intrinsic valuation method that estimates the present value of a company's expected future free cash flows, discounted at an appropriate rate reflecting the risk of those cash flows.
+
+**Core Principle:** The value of a business equals the present value of all future cash flows it will generate.
+
+**Formula:**
+
+```
+Enterprise Value = Sum of [FCF_t / (1 + WACC)^t] + Terminal Value / (1 + WACC)^n
+```
+
+Where:
+
+- FCF_t = Free Cash Flow in year t
+- WACC = Weighted Average Cost of Capital
+- n = number of projection years
+
+### Step 1: Historical Analysis
+
+Before projecting, analyze 3-5 years of historical financials:
+
+- **Revenue growth rates** - Identify organic vs acquisition-driven growth
+- **Margin trends** - Gross, operating, and net margin trajectories
+- **Capital intensity** - CapEx as % of revenue
+- **Working capital** - Cash conversion cycle trends
+- **Free cash flow conversion** - FCF / Net Income ratio
+
+### Step 2: Revenue Projections
+
+**Approaches:**
+
+1. **Top-down:** Market size x Market share x Pricing
+2. **Bottom-up:** Units x Price, or Customers x ARPU
+3. **Growth rate extrapolation:** Historical growth with decay
+
+**Revenue Projection Best Practices:**
+
+- Use 5-7 year explicit projection period
+- Growth should converge toward GDP growth by terminal year
+- Support assumptions with market data and management guidance
+- Model revenue by segment/product line when possible
+
+### Step 3: Free Cash Flow Calculation
+
+**Unlevered Free Cash Flow (UFCF):**
+
+```
+UFCF = EBIT x (1 - Tax Rate)
+     + Depreciation & Amortization
+     - Capital Expenditures
+     - Changes in Net Working Capital
+```
+
+**Key Drivers:**
+
+- Operating margin trajectory
+- CapEx as % of revenue (maintenance vs growth)
+- Working capital requirements (DSO, DIO, DPO)
+- Tax rate (effective vs marginal)
+
+### Step 4: WACC Calculation
+
+**Weighted Average Cost of Capital:**
+
+```
+WACC = (E/V x Re) + (D/V x Rd x (1 - T))
+```
+
+Where:
+
+- E/V = Equity weight (market value)
+- D/V = Debt weight (market value)
+- Re = Cost of equity
+- Rd = Cost of debt (pre-tax)
+- T = Marginal tax rate
+
+#### Cost of Equity (CAPM)
+
+```
+Re = Rf + Beta x (Rm - Rf) + Size Premium + Company-Specific Risk
+```
+
+| Component                 | Description                        | Typical Range |
+| ------------------------- | ---------------------------------- | ------------- |
+| Risk-Free Rate (Rf)       | 10-year Treasury yield             | 3.5% - 5.0%   |
+| Equity Risk Premium (ERP) | Market return above risk-free      | 5.0% - 7.0%   |
+| Beta                      | Systematic risk relative to market | 0.5 - 2.0     |
+| Size Premium              | Small-cap additional risk          | 0% - 5%       |
+| Company-Specific Risk     | Unique risk factors                | 0% - 5%       |
+
+**Beta Estimation:**
+
+- Use 2-5 year weekly returns against broad market index
+- Unlevered betas for comparability, then re-lever to target capital structure
+- Consider industry median beta for stability
+
+#### Cost of Debt
+
+```
+Rd = Yield on comparable-maturity corporate bonds
+   OR
+Rd = Risk-Free Rate + Credit Spread
+```
+
+**Credit Spread by Rating:**
+| Rating | Typical Spread |
+|--------|---------------|
+| AAA | 0.5% - 1.0% |
+| AA | 1.0% - 1.5% |
+| A | 1.5% - 2.0% |
+| BBB | 2.0% - 3.0% |
+| BB | 3.0% - 5.0% |
+| B | 5.0% - 8.0% |
+
+### Step 5: Terminal Value
+
+Terminal value typically represents 60-80% of total enterprise value. Use two methods and cross-check.
+
+#### Perpetuity Growth Method
+
+```
+TV = FCF_n x (1 + g) / (WACC - g)
+```
+
+Where g = terminal growth rate (typically 2.0% - 3.0%, should not exceed long-term GDP growth)
+
+**Sensitivity:** Terminal value is highly sensitive to g. A 0.5% change in g can move enterprise value by 15-25%.
+
+#### Exit Multiple Method
+
+```
+TV = Terminal Year EBITDA x Exit EV/EBITDA Multiple
+```
+
+**Exit Multiple Selection:**
+
+- Use current trading multiples of comparable companies
+- Consider whether current multiples are at historical highs/lows
+- Apply a discount for lack of marketability if private
+
+**Cross-Check:** Both methods should yield similar results. Large discrepancies signal inconsistent assumptions.
+
+### Step 6: Enterprise to Equity Bridge
+
+```
+Enterprise Value
+- Net Debt (Total Debt - Cash)
+- Minority Interest
+- Preferred Equity
++ Equity Method Investments
+= Equity Value
+
+Equity Value / Diluted Shares Outstanding = Value Per Share
+```
+
+### Step 7: Sensitivity Analysis
+
+Always present results as a range, not a single point estimate.
+
+**Standard Sensitivity Tables:**
+
+1. WACC vs Terminal Growth Rate
+2. WACC vs Exit Multiple
+3. Revenue Growth vs Operating Margin
+
+**Scenario Analysis:**
+
+- Base case: Management guidance / consensus estimates
+- Bull case: Upside scenario with faster growth or margin expansion
+- Bear case: Downside scenario with slower growth or margin compression
+
+## 2. Comparable Company Analysis
+
+### Methodology
+
+1. **Select peer group** - Similar size, industry, growth profile, and margins
+2. **Calculate trading multiples** for each peer
+3. **Determine appropriate multiple range**
+4. **Apply to target company's metrics**
+
+### Common Multiples
+
+| Multiple   | When to Use                                 |
+| ---------- | ------------------------------------------- |
+| EV/Revenue | Pre-profit companies, high-growth tech      |
+| EV/EBITDA  | Most common for mature companies            |
+| EV/EBIT    | When D&A differs significantly across peers |
+| P/E        | Stable earnings, financial services         |
+| P/B        | Banks, insurance, asset-heavy industries    |
+| EV/FCF     | Capital-light businesses with clean FCF     |
+
+### Peer Selection Criteria
+
+- **Industry:** Same or closely adjacent sectors
+- **Size:** Within 0.5x to 2x of target revenue/market cap
+- **Geography:** Same primary markets
+- **Growth profile:** Similar revenue growth rates (within 5-10%)
+- **Margin profile:** Similar operating margin structure
+- **Business model:** Comparable revenue mix and customer base
+
+### Premium/Discount Adjustments
+
+| Factor          | Adjustment                           |
+| --------------- | ------------------------------------ |
+| Higher growth   | Premium of 1-3x on EV/EBITDA         |
+| Lower margins   | Discount of 1-2x                     |
+| Smaller scale   | Discount of 10-20%                   |
+| Private company | Discount of 15-30% (illiquidity)     |
+| Control premium | Premium of 20-40% (for acquisitions) |
+
+## 3. Precedent Transaction Analysis
+
+### Methodology
+
+1. **Identify comparable transactions** in same industry
+2. **Calculate transaction multiples** (EV/Revenue, EV/EBITDA)
+3. **Adjust for market conditions** and deal-specific factors
+4. **Apply adjusted multiples** to target
+
+### Key Considerations
+
+- Transactions include control premiums (typically 20-40%)
+- Market conditions at time of deal affect multiples
+- Strategic vs financial buyer valuations differ
+- Consider synergy expectations embedded in price
+- More recent transactions carry greater relevance
+
+## 4. Valuation Framework Selection
+
+| Situation               | Primary Method                    | Secondary Method           |
+| ----------------------- | --------------------------------- | -------------------------- |
+| Profitable, stable      | DCF                               | Comparable companies       |
+| High growth, pre-profit | Comparable companies (EV/Revenue) | DCF with scenario analysis |
+| M&A target              | Precedent transactions            | DCF                        |
+| Asset-heavy, cyclical   | Asset-based valuation             | Normalized DCF             |
+| Financial institution   | Dividend discount model           | P/B, P/E comps             |
+| Distressed              | Liquidation value                 | Restructured DCF           |
+
+## 5. Common Pitfalls
+
+1. **Hockey stick projections** - Unrealistic growth acceleration in later years
+2. **Terminal value dominance** - If TV > 80% of EV, shorten projection period or question assumptions
+3. **Circular references** - WACC depends on equity value which depends on WACC
+4. **Ignoring working capital** - Can significantly affect FCF
+5. **Single-point estimates** - Always present as a range
+6. **Stale comparables** - Market conditions change; update regularly
+7. **Confirmation bias** - Don't work backward from a desired conclusion
+8. **Ignoring dilution** - Use fully diluted shares (treasury stock method for options)

package/_vendor/claude-skills-finance/scripts/budget_variance_analyzer.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+"""
+Budget Variance Analyzer
+
+Analyzes actual vs budget vs prior year performance with materiality
+threshold filtering, favorable/unfavorable classification, and
+department/category breakdown.
+
+Usage:
+    python budget_variance_analyzer.py budget_data.json
+    python budget_variance_analyzer.py budget_data.json --format json
+    python budget_variance_analyzer.py budget_data.json --threshold-pct 5 --threshold-amt 25000
+"""
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def safe_divide(numerator: float, denominator: float, default: float = 0.0) -> float:
+    """Safely divide two numbers, returning default if denominator is zero."""
+    if denominator == 0 or denominator is None:
+        return default
+    return numerator / denominator
+
+
+class BudgetVarianceAnalyzer:
+    """Analyze budget variances with materiality filtering and classification."""
+
+    def __init__(
+        self,
+        data: Dict[str, Any],
+        threshold_pct: float = 10.0,
+        threshold_amt: float = 50000.0,
+    ) -> None:
+        """
+        Initialize the analyzer.
+
+        Args:
+            data: Budget data with line items
+            threshold_pct: Materiality threshold as percentage (default 10%)
+            threshold_amt: Materiality threshold as dollar amount (default $50K)
+        """
+        self.line_items: List[Dict[str, Any]] = data.get("line_items", [])
+        self.period: str = data.get("period", "Current Period")
+        self.company: str = data.get("company", "Company")
+        self.threshold_pct = threshold_pct
+        self.threshold_amt = threshold_amt
+        self.variances: List[Dict[str, Any]] = []
+        self.material_variances: List[Dict[str, Any]] = []
+        self.summary: Dict[str, Any] = {}
+
+    def classify_favorability(
+        self, line_type: str, variance_amount: float
+    ) -> str:
+        """
+        Classify variance as favorable or unfavorable.
+
+        Revenue: over budget = favorable
+        Expense: under budget = favorable
+        """
+        if line_type.lower() in ("revenue", "income", "sales"):
+            return "Favorable" if variance_amount > 0 else "Unfavorable"
+        else:
+            # For expenses, under budget (negative variance) is favorable
+            return "Favorable" if variance_amount < 0 else "Unfavorable"
+
+    def calculate_variances(self) -> List[Dict[str, Any]]:
+        """Calculate variances for all line items."""
+        self.variances = []
+
+        for item in self.line_items:
+            name = item.get("name", "Unknown")
+            line_type = item.get("type", "expense")
+            department = item.get("department", "General")
+            category = item.get("category", "Other")
+            actual = item.get("actual", 0)
+            budget = item.get("budget", 0)
+            prior_year = item.get("prior_year", None)
+
+            # Budget variance
+            budget_var_amt = actual - budget
+            budget_var_pct = safe_divide(budget_var_amt, budget) * 100
+
+            # Prior year variance (if available)
+            py_var_amt = (actual - prior_year) if prior_year is not None else None
+            py_var_pct = (
+                safe_divide(py_var_amt, prior_year) * 100
+                if prior_year is not None
+                else None
+            )
+
+            favorability = self.classify_favorability(line_type, budget_var_amt)
+
+            is_material = (
+                abs(budget_var_pct) >= self.threshold_pct
+                or abs(budget_var_amt) >= self.threshold_amt
+            )
+
+            variance_record = {
+                "name": name,
+                "type": line_type,
+                "department": department,
+                "category": category,
+                "actual": actual,
+                "budget": budget,
+                "prior_year": prior_year,
+                "budget_variance_amount": budget_var_amt,
+                "budget_variance_pct": round(budget_var_pct, 2),
+                "prior_year_variance_amount": py_var_amt,
+                "prior_year_variance_pct": (
+                    round(py_var_pct, 2) if py_var_pct is not None else None
+                ),
+                "favorability": favorability,
+                "is_material": is_material,
+            }
+
+            self.variances.append(variance_record)
+
+        # Filter material variances
+        self.material_variances = [v for v in self.variances if v["is_material"]]
+
+        return self.variances
+
+    def department_summary(self) -> Dict[str, Dict[str, Any]]:
+        """Summarize variances by department."""
+        departments: Dict[str, Dict[str, float]] = {}
+
+        for v in self.variances:
+            dept = v["department"]
+            if dept not in departments:
+                departments[dept] = {
+                    "total_actual": 0.0,
+                    "total_budget": 0.0,
+                    "total_variance": 0.0,
+                    "favorable_count": 0,
+                    "unfavorable_count": 0,
+                    "line_count": 0,
+                }
+
+            departments[dept]["total_actual"] += v["actual"]
+            departments[dept]["total_budget"] += v["budget"]
+            departments[dept]["total_variance"] += v["budget_variance_amount"]
+            departments[dept]["line_count"] += 1
+            if v["favorability"] == "Favorable":
+                departments[dept]["favorable_count"] += 1
+            else:
+                departments[dept]["unfavorable_count"] += 1
+
+        # Add variance percentage
+        for dept_data in departments.values():
+            dept_data["variance_pct"] = round(
+                safe_divide(
+                    dept_data["total_variance"], dept_data["total_budget"]
+                )
+                * 100,
+                2,
+            )
+
+        return departments
+
+    def category_summary(self) -> Dict[str, Dict[str, Any]]:
+        """Summarize variances by category."""
+        categories: Dict[str, Dict[str, float]] = {}
+
+        for v in self.variances:
+            cat = v["category"]
+            if cat not in categories:
+                categories[cat] = {
+                    "total_actual": 0.0,
+                    "total_budget": 0.0,
+                    "total_variance": 0.0,
+                    "line_count": 0,
+                }
+
+            categories[cat]["total_actual"] += v["actual"]
+            categories[cat]["total_budget"] += v["budget"]
+            categories[cat]["total_variance"] += v["budget_variance_amount"]
+            categories[cat]["line_count"] += 1
+
+        for cat_data in categories.values():
+            cat_data["variance_pct"] = round(
+                safe_divide(
+                    cat_data["total_variance"], cat_data["total_budget"]
+                )
+                * 100,
+                2,
+            )
+
+        return categories
+
+    def generate_executive_summary(self) -> Dict[str, Any]:
+        """Generate an executive summary of the variance analysis."""
+        total_actual = sum(
+            v["actual"] for v in self.variances if v["type"].lower() in ("revenue", "income", "sales")
+        )
+        total_budget = sum(
+            v["budget"] for v in self.variances if v["type"].lower() in ("revenue", "income", "sales")
+        )
+        total_expense_actual = sum(
+            v["actual"] for v in self.variances if v["type"].lower() not in ("revenue", "income", "sales")
+        )
+        total_expense_budget = sum(
+            v["budget"] for v in self.variances if v["type"].lower() not in ("revenue", "income", "sales")
+        )
+
+        revenue_variance = total_actual - total_budget
+        expense_variance = total_expense_actual - total_expense_budget
+
+        favorable_count = sum(
+            1 for v in self.variances if v["favorability"] == "Favorable"
+        )
+        unfavorable_count = sum(
+            1 for v in self.variances if v["favorability"] == "Unfavorable"
+        )
+
+        self.summary = {
+            "period": self.period,
+            "company": self.company,
+            "total_line_items": len(self.variances),
+            "material_variances_count": len(self.material_variances),
+            "favorable_count": favorable_count,
+            "unfavorable_count": unfavorable_count,
+            "revenue": {
+                "actual": total_actual,
+                "budget": total_budget,
+                "variance_amount": revenue_variance,
+                "variance_pct": round(
+                    safe_divide(revenue_variance, total_budget) * 100, 2
+                ),
+            },
+            "expenses": {
+                "actual": total_expense_actual,
+                "budget": total_expense_budget,
+                "variance_amount": expense_variance,
+                "variance_pct": round(
+                    safe_divide(expense_variance, total_expense_budget) * 100, 2
+                ),
+            },
+            "net_impact": revenue_variance - expense_variance,
+            "materiality_thresholds": {
+                "percentage": self.threshold_pct,
+                "amount": self.threshold_amt,
+            },
+        }
+
+        return self.summary
+
+    def run_analysis(self) -> Dict[str, Any]:
+        """Run the complete variance analysis."""
+        self.calculate_variances()
+        dept_summary = self.department_summary()
+        cat_summary = self.category_summary()
+        exec_summary = self.generate_executive_summary()
+
+        return {
+            "executive_summary": exec_summary,
+            "all_variances": self.variances,
+            "material_variances": self.material_variances,
+            "department_summary": dept_summary,
+            "category_summary": cat_summary,
+        }
+
+    def format_text(self, results: Dict[str, Any]) -> str:
+        """Format results as human-readable text."""
+        lines: List[str] = []
+        lines.append("=" * 70)
+        lines.append("BUDGET VARIANCE ANALYSIS")
+        lines.append("=" * 70)
+
+        summary = results["executive_summary"]
+        lines.append(f"\n  Company: {summary['company']}")
+        lines.append(f"  Period:  {summary['period']}")
+
+        def fmt_money(val: float) -> str:
+            sign = "+" if val > 0 else ""
+            if abs(val) >= 1e6:
+                return f"{sign}${val / 1e6:,.2f}M"
+            if abs(val) >= 1e3:
+                return f"{sign}${val / 1e3:,.1f}K"
+            return f"{sign}${val:,.2f}"
+
+        lines.append(f"\n--- EXECUTIVE SUMMARY ---")
+        rev = summary["revenue"]
+        exp = summary["expenses"]
+        lines.append(
+            f"  Revenue:  Actual {fmt_money(rev['actual'])} vs "
+            f"Budget {fmt_money(rev['budget'])} "
+            f"({fmt_money(rev['variance_amount'])}, {rev['variance_pct']:+.1f}%)"
+        )
+        lines.append(
+            f"  Expenses: Actual {fmt_money(exp['actual'])} vs "
+            f"Budget {fmt_money(exp['budget'])} "
+            f"({fmt_money(exp['variance_amount'])}, {exp['variance_pct']:+.1f}%)"
+        )
+        lines.append(f"  Net Impact: {fmt_money(summary['net_impact'])}")
+        lines.append(
+            f"  Total Items: {summary['total_line_items']}  |  "
+            f"Material: {summary['material_variances_count']}  |  "
+            f"Favorable: {summary['favorable_count']}  |  "
+            f"Unfavorable: {summary['unfavorable_count']}"
+        )
+
+        # Material variances
+        material = results["material_variances"]
+        if material:
+            lines.append(f"\n--- MATERIAL VARIANCES ---")
+            lines.append(
+                f"  (Threshold: {self.threshold_pct}% or "
+                f"${self.threshold_amt:,.0f})"
+            )
+            for v in material:
+                lines.append(
+                    f"\n  {v['name']} ({v['department']})"
+                )
+                lines.append(
+                    f"    Actual: {fmt_money(v['actual'])} | "
+                    f"Budget: {fmt_money(v['budget'])}"
+                )
+                lines.append(
+                    f"    Variance: {fmt_money(v['budget_variance_amount'])} "
+                    f"({v['budget_variance_pct']:+.1f}%) - {v['favorability']}"
+                )
+
+        # Department summary
+        dept = results["department_summary"]
+        if dept:
+            lines.append(f"\n--- DEPARTMENT SUMMARY ---")
+            for dept_name, d in dept.items():
+                lines.append(
+                    f"  {dept_name}: Variance {fmt_money(d['total_variance'])} "
+                    f"({d['variance_pct']:+.1f}%) | "
+                    f"Fav: {d['favorable_count']} / Unfav: {d['unfavorable_count']}"
+                )
+
+        # Category summary
+        cat = results["category_summary"]
+        if cat:
+            lines.append(f"\n--- CATEGORY SUMMARY ---")
+            for cat_name, c in cat.items():
+                lines.append(
+                    f"  {cat_name}: Variance {fmt_money(c['total_variance'])} "
+                    f"({c['variance_pct']:+.1f}%)"
+                )
+
+        lines.append("\n" + "=" * 70)
+        return "\n".join(lines)
+
+
+def main() -> None:
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Analyze budget variances with materiality filtering"
+    )
+    parser.add_argument(
+        "input_file",
+        help="Path to JSON file with budget data",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    parser.add_argument(
+        "--threshold-pct",
+        type=float,
+        default=10.0,
+        help="Materiality threshold percentage (default: 10)",
+    )
+    parser.add_argument(
+        "--threshold-amt",
+        type=float,
+        default=50000.0,
+        help="Materiality threshold dollar amount (default: 50000)",
+    )
+
+    args = parser.parse_args()
+
+    try:
+        with open(args.input_file, "r") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        print(f"Error: File '{args.input_file}' not found.", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON in '{args.input_file}': {e}", file=sys.stderr)
+        sys.exit(1)
+
+    analyzer = BudgetVarianceAnalyzer(
+        data,
+        threshold_pct=args.threshold_pct,
+        threshold_amt=args.threshold_amt,
+    )
+
+    results = analyzer.run_analysis()
+
+    if args.format == "json":
+        print(json.dumps(results, indent=2))
+    else:
+        print(analyzer.format_text(results))
+
+
+if __name__ == "__main__":
+    main()