shortcutxl 0.2.0

package/skills/integrations/calcbench.md

@@ -0,0 +1,315 @@
+**Calcbench Excel Formula Guide**
+
+**Intro**
+You have full access to Calcbench financial data through the Calcbench Excel Add-in, but you should only pull Calcbench data **when the user explicitly tells you to**. Calcbench specializes in SEC XBRL filings data, providing standardized fundamental data for US public companies directly from regulatory filings. Data goes back to 2008 when XBRL became mandatory. You can retrieve any data point by writing CalcbenchData formulas directly in Excel cells.
+
+**IMPORTANT:** Before completing a task involving Calcbench, you must verify:
+1. Your CalcbenchData formulas do not return errors.
+2. All values should seem reasonable and make intuitive sense based on your general knowledge of finance.
+3. Use cell references for tickers, metrics, and periods when possible as opposed to hardcoded values.
+4. Be aware that Calcbench covers US public companies only (SEC filers).
+5. Data is sourced from SEC filings, so it reflects as-reported values.
+
+You should essentially gut check every value that shows up. If there are any errors or the values seem wrong, you likely wrote the formula syntax incorrectly or are using invalid metric names. Please correct the formula until it outputs the proper value.
+
+---
+
+**Calcbench Excel Functions Overview**
+
+Calcbench provides these Excel functions:
+
+| Function | Purpose | Use Case |
+|----------|---------|----------|
+| CalcbenchData | Standard metrics | Income statement, balance sheet, cash flow |
+| CalcbenchXBRL | Raw XBRL tags | Access any XBRL element directly |
+| CalcbenchRatio | Financial ratios | Pre-calculated ratios |
+
+---
+
+**1. CalcbenchData - Standard Metrics**
+
+Returns standardized financial data for US public companies.
+
+**Syntax:** =CalcbenchData("Metric", "Ticker", Year, Period)
+
+**Parameters:**
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| Metric | Standardized metric name | Yes |
+| Ticker | Stock ticker symbol | Yes |
+| Year | Fiscal year (e.g., 2024) | Yes |
+| Period | 0=Annual, 1=Q1, 2=Q2, 3=Q3, 4=Q4 | Yes |
+
+**Period Values:**
+| Value | Meaning |
+|-------|---------|
+| 0 | Annual (full fiscal year) |
+| 1 | Q1 |
+| 2 | Q2 |
+| 3 | Q3 |
+| 4 | Q4 |
+
+**Examples:**
+=CalcbenchData("Revenue", "AAPL", 2024, 0)
+-> Apple's FY2024 annual revenue.
+
+=CalcbenchData("NetIncome", "MSFT", 2024, 1)
+-> Microsoft's Q1 2024 net income.
+
+=CalcbenchData("TotalAssets", "GOOGL", 2023, 0)
+-> Alphabet's 2023 total assets.
+
+**Using Cell References:**
+=CalcbenchData("Revenue", A1, B1, C1)
+-> Revenue for ticker in A1, year in B1, period in C1.
+
+---
+
+**2. CalcbenchXBRL - Raw XBRL Tags**
+
+Returns data using raw XBRL taxonomy elements for precise SEC filing data.
+
+**Syntax:** =CalcbenchXBRL("XBRLTag", "Ticker", Year, Period)
+
+**Examples:**
+=CalcbenchXBRL("us-gaap:Revenues", "AAPL", 2024, 0)
+-> Apple revenue using XBRL tag.
+
+=CalcbenchXBRL("us-gaap:NetIncomeLoss", "MSFT", 2024, 0)
+-> Microsoft net income using XBRL tag.
+
+---
+
+**3. CalcbenchRatio - Financial Ratios**
+
+Returns pre-calculated financial ratios.
+
+**Syntax:** =CalcbenchRatio("RatioName", "Ticker", Year, Period)
+
+**Examples:**
+=CalcbenchRatio("CurrentRatio", "AAPL", 2024, 0)
+-> Apple's current ratio.
+
+=CalcbenchRatio("DebtToEquity", "MSFT", 2024, 0)
+-> Microsoft's debt/equity ratio.
+
+---
+
+**4. Common Metrics Reference**
+
+**Income Statement:**
+| Metric | Description |
+|--------|-------------|
+| `Revenue` | Total revenue/net sales |
+| `CostOfRevenue` | Cost of goods sold |
+| `GrossProfit` | Gross profit |
+| `OperatingExpenses` | Total operating expenses |
+| `ResearchAndDevelopment` | R&D expenses |
+| `SellingGeneralAndAdmin` | SG&A expenses |
+| `OperatingIncome` | Operating income |
+| `InterestExpense` | Interest expense |
+| `InterestIncome` | Interest income |
+| `OtherIncome` | Other income/expense |
+| `PretaxIncome` | Income before taxes |
+| `IncomeTaxExpense` | Income tax expense |
+| `NetIncome` | Net income |
+| `EarningsPerShareBasic` | Basic EPS |
+| `EarningsPerShareDiluted` | Diluted EPS |
+| `WeightedAverageSharesBasic` | Weighted avg shares (basic) |
+| `WeightedAverageSharesDiluted` | Weighted avg shares (diluted) |
+
+**Balance Sheet - Assets:**
+| Metric | Description |
+|--------|-------------|
+| `TotalAssets` | Total assets |
+| `CurrentAssets` | Total current assets |
+| `CashAndEquivalents` | Cash and cash equivalents |
+| `ShortTermInvestments` | Marketable securities |
+| `AccountsReceivable` | Accounts receivable, net |
+| `Inventory` | Inventories |
+| `PrepaidExpenses` | Prepaid expenses |
+| `OtherCurrentAssets` | Other current assets |
+| `PropertyPlantEquipment` | PP&E, net |
+| `Goodwill` | Goodwill |
+| `IntangibleAssets` | Intangible assets |
+| `LongTermInvestments` | Long-term investments |
+| `OtherAssets` | Other non-current assets |
+
+**Balance Sheet - Liabilities:**
+| Metric | Description |
+|--------|-------------|
+| `TotalLiabilities` | Total liabilities |
+| `CurrentLiabilities` | Total current liabilities |
+| `AccountsPayable` | Accounts payable |
+| `AccruedExpenses` | Accrued liabilities |
+| `ShortTermDebt` | Short-term debt |
+| `CurrentPortionLongTermDebt` | Current portion of LT debt |
+| `DeferredRevenue` | Deferred revenue |
+| `LongTermDebt` | Long-term debt |
+| `OtherLiabilities` | Other liabilities |
+
+**Balance Sheet - Equity:**
+| Metric | Description |
+|--------|-------------|
+| `StockholdersEquity` | Total shareholders' equity |
+| `CommonStock` | Common stock |
+| `AdditionalPaidInCapital` | Additional paid-in capital |
+| `RetainedEarnings` | Retained earnings |
+| `TreasuryStock` | Treasury stock |
+| `AccumulatedOtherComprehensiveIncome` | AOCI |
+
+**Cash Flow Statement:**
+| Metric | Description |
+|--------|-------------|
+| `CashFlowFromOperations` | Operating cash flow |
+| `DepreciationAndAmortization` | D&A |
+| `StockBasedCompensation` | Stock-based comp |
+| `ChangeInWorkingCapital` | Working capital changes |
+| `CashFlowFromInvesting` | Investing cash flow |
+| `CapitalExpenditures` | Capital expenditures |
+| `Acquisitions` | Acquisitions |
+| `CashFlowFromFinancing` | Financing cash flow |
+| `DividendsPaid` | Dividends paid |
+| `ShareRepurchases` | Stock buybacks |
+| `DebtIssuance` | Debt issued |
+| `DebtRepayment` | Debt repaid |
+| `FreeCashFlow` | Free cash flow (CFO - CapEx) |
+| `NetChangeInCash` | Net change in cash |
+
+**Ratios (use with CalcbenchRatio):**
+| Ratio | Description |
+|-------|-------------|
+| `CurrentRatio` | Current assets / current liabilities |
+| `QuickRatio` | (Current assets - inventory) / current liabilities |
+| `DebtToEquity` | Total debt / equity |
+| `DebtToAssets` | Total debt / total assets |
+| `GrossMargin` | Gross profit / revenue |
+| `OperatingMargin` | Operating income / revenue |
+| `NetMargin` | Net income / revenue |
+| `ROE` | Net income / average equity |
+| `ROA` | Net income / average assets |
+| `AssetTurnover` | Revenue / average assets |
+| `InventoryTurnover` | COGS / average inventory |
+| `DaysInventory` | 365 / inventory turnover |
+| `DaysSalesOutstanding` | (AR / revenue) * 365 |
+| `DaysPayableOutstanding` | (AP / COGS) * 365 |
+
+---
+
+**5. Example Formulas by Use Case**
+
+**Income Statement Analysis:**
+=CalcbenchData("Revenue", "AAPL", 2024, 0)
+-> Apple FY2024 revenue.
+
+=CalcbenchData("NetIncome", "MSFT", 2024, 0)
+-> Microsoft FY2024 net income.
+
+=CalcbenchData("EarningsPerShareDiluted", "GOOGL", 2024, 0)
+-> Google FY2024 diluted EPS.
+
+**Quarterly Comparison:**
+=CalcbenchData("Revenue", "AAPL", 2024, 1)
+-> Apple Q1 2024 revenue.
+
+=CalcbenchData("Revenue", "AAPL", 2024, 2)
+-> Apple Q2 2024 revenue.
+
+**Balance Sheet:**
+=CalcbenchData("TotalAssets", "JPM", 2024, 0)
+-> JPMorgan total assets.
+
+=CalcbenchData("CashAndEquivalents", "AAPL", 2024, 0)
+-> Apple cash position.
+
+=CalcbenchData("LongTermDebt", "MSFT", 2024, 0)
+-> Microsoft long-term debt.
+
+**Cash Flow:**
+=CalcbenchData("CashFlowFromOperations", "AAPL", 2024, 0)
+-> Apple operating cash flow.
+
+=CalcbenchData("FreeCashFlow", "GOOGL", 2024, 0)
+-> Google free cash flow.
+
+=CalcbenchData("CapitalExpenditures", "AMZN", 2024, 0)
+-> Amazon capex.
+
+**Financial Ratios:**
+=CalcbenchRatio("CurrentRatio", "AAPL", 2024, 0)
+-> Apple current ratio.
+
+=CalcbenchRatio("DebtToEquity", "MSFT", 2024, 0)
+-> Microsoft debt/equity.
+
+=CalcbenchRatio("ROE", "GOOGL", 2024, 0)
+-> Google return on equity.
+
+**Multi-Year Comparison:**
+=CalcbenchData("Revenue", "AAPL", 2024, 0) / CalcbenchData("Revenue", "AAPL", 2023, 0) - 1
+-> Apple YoY revenue growth.
+
+**Industry Comparison:**
+=CalcbenchData("GrossProfit", "AAPL", 2024, 0) / CalcbenchData("Revenue", "AAPL", 2024, 0)
+-> Apple gross margin (manual calculation).
+
+---
+
+**6. Data Coverage Notes**
+
+**Coverage:**
+- US public companies only (SEC filers)
+- Data from 2008 onwards (when XBRL became mandatory)
+- 10-K filings for annual data
+- 10-Q filings for quarterly data
+
+**Data Timing:**
+- Data available within days of SEC filing
+- As-reported values (not restated)
+- Fiscal year end dates vary by company
+
+**Special Cases:**
+- Banks/financials may have different line items
+- Insurance companies have specialized metrics
+- REITs use FFO instead of net income
+
+---
+
+**7. Error Handling**
+
+**Common Errors:**
+| Error | Cause | Solution |
+|-------|-------|----------|
+| #VALUE! | Invalid ticker | Verify ticker is a US public company |
+| #N/A | Data not available | Company may not have filed yet, or metric doesn't apply |
+| #NAME? | Function not recognized | Verify Calcbench add-in is enabled |
+| 0 or blank | No data for period | Check if company files quarterly or is fiscal year mismatch |
+| Wrong metric | Different industry | Financial companies use different metrics |
+
+**Debugging Tips:**
+1. Verify ticker on SEC EDGAR
+2. Check when company last filed (10-K, 10-Q)
+3. Confirm metric name spelling (case-sensitive)
+4. For quarterly data, ensure period is 1-4, not 0
+5. Some companies only file annually (use period=0)
+6. Fiscal year may not align with calendar year
+
+---
+
+**Final Checklist:**
+- Is the ticker a US public company (SEC filer)?
+- Is the metric name spelled correctly (CamelCase)?
+- Is the year correct (fiscal year, not calendar year for some companies)?
+- Is the period correct? (0=annual, 1-4=quarters)
+- Has the company filed for that period yet?
+- Does the metric apply to this type of company?
+- Is the Calcbench add-in connected?
+
+---
+
+**Additional Resources:**
+- Calcbench Platform: https://www.calcbench.com/
+- Excel Add-in: https://www.calcbench.com/excel
+- Metric Documentation: https://www.calcbench.com/docs/metrics
+- SEC EDGAR: https://www.sec.gov/edgar/
+- Note: Free for CFA charterholders through CFA Institute partnership