better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/finance/finance-3-statement-model.md

@@ -0,0 +1,451 @@
+---
+title: "3 Statement Model — Build integrated IS/BS/CF financial workbooks in Excel"
+sidebar_label: "3 Statement Model"
+description: "Build integrated IS/BS/CF financial workbooks in Excel"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# 3 Statement Model
+
+Build integrated IS/BS/CF financial workbooks in Excel.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/finance/3-statement-model` |
+| Path | `optional-skills/finance\3-statement-model` |
+| Version | `1.0.0` |
+| Author | Anthropic (adapted by Nous Research) |
+| License | Apache-2.0 |
+| Platforms | linux, macos, windows |
+| Tags | `finance`, `three-statement`, `income-statement`, `balance-sheet`, `cash-flow`, `excel`, `openpyxl`, `modeling` |
+| Related skills | [`excel-author`](/docs/user-guide/skills/optional/finance/finance-excel-author), [`pptx-author`](/docs/user-guide/skills/optional/finance/finance-pptx-author), [`dcf-model`](/docs/user-guide/skills/optional/finance/finance-dcf-model), [`lbo-model`](/docs/user-guide/skills/optional/finance/finance-lbo-model) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+## Environment
+
+This skill assumes **headless openpyxl** — you are producing an .xlsx file on disk.
+Follow the `excel-author` skill's conventions for cell coloring, formulas, named ranges, and sensitivity tables.
+Recalculate before delivery: `python /path/to/excel-author/scripts/recalc.py ./out/model.xlsx`.
+
+# 3-Statement Financial Model Template Completion
+
+Complete and populate integrated financial model templates with proper linkages between Income Statement, Balance Sheet, and Cash Flow Statement.
+
+## ⚠️ CRITICAL PRINCIPLES — Read Before Populating Any Template
+
+**Formulas over hardcodes (non-negotiable):**
+- Every projection cell, roll-forward, linkage, and subtotal MUST be an Excel formula — never a pre-computed value
+- When using Python/openpyxl: write formula strings (`ws["D15"] = "=D14*(1+Assumptions!$B$5)"`), NOT computed results (`ws["D15"] = 12500`)
+- The ONLY cells that should contain hardcoded numbers are: (1) historical actuals, (2) assumption drivers in the Assumptions tab
+- If you find yourself computing a value in Python and writing the result to a cell — STOP. Write the formula instead.
+- Why: the model must flex when scenarios toggle or assumptions change. Hardcodes break every downstream integrity check silently.
+
+**Verify step-by-step with the user:**
+1. **After mapping the template** → show the user which tabs/sections you've identified and confirm before touching any cells
+2. **After populating historicals** → show the user the historical block and confirm values/periods match source data
+3. **After building IS projections** → run the subtotal checks, show the user the projected IS, confirm before moving to BS
+4. **After building BS** → show the user the balance check (Assets = L+E) for every period, confirm before moving to CF
+5. **After building CF** → show the user the cash tie-out (CF ending cash = BS cash), confirm before finalizing
+6. **Do NOT populate the entire model end-to-end and present it complete** — break at each statement, show the work, catch errors early
+
+## Formatting — Professional Blue/Grey Palette (Default unless template/user specifies otherwise)
+
+**Keep colors minimal.** Use only blues and greys for cell fills. Do NOT introduce greens, yellows, oranges, or multiple accent colors — a clean model uses restraint.
+
+| Element | Fill | Font |
+|---|---|---|
+| Section headers (IS / BS / CF titles) | Dark blue `#1F4E79` | White bold |
+| Column headers (FY2024A, FY2025E, etc.) | Light blue `#D9E1F2` | Black bold |
+| Input cells (historicals, assumption drivers) | Light grey `#F2F2F2` or white | Blue `#0000FF` |
+| Formula cells | White | Black |
+| Cross-tab links | White | Green `#008000` |
+| Check rows / key totals | Medium blue `#BDD7EE` | Black bold |
+
+**That's 3 blues + 1 grey + white.** If the template has its own color scheme, follow the template instead.
+
+Font color signals *what* a cell is (input/formula/link). Fill color signals *where* you are (header/data/check).
+
+## Model Structure
+
+### Identifying Template Tab Organization
+
+Templates vary in their tab naming conventions and organization. Before populating, review all tabs to understand the template's structure. Below are common tab names and their typical contents:
+
+| Common Tab Names | Contents to Look For |
+|------------------|----------------------|
+| IS, P&L, Income Statement | Income Statement |
+| BS, Balance Sheet | Balance Sheet |
+| CF, CFS, Cash Flow | Cash Flow Statement |
+| WC, Working Capital | Working Capital Schedule |
+| DA, D&A, Depreciation, PP&E | Depreciation & Amortization Schedule |
+| Debt, Debt Schedule | Debt Schedule |
+| NOL, Tax, DTA | Net Operating Loss Schedule |
+| Assumptions, Inputs, Drivers | Driver assumptions and inputs |
+| Checks, Audit, Validation | Error-checking dashboard |
+
+**Template Review Checklist**
+- Identify which tabs exist in the template (not all templates include every schedule)
+- Note any template-specific tabs not listed above
+- Understand tab dependencies (e.g., which schedules feed into the main statements)
+- Locate input cells vs. formula cells on each tab
+
+### Understanding Template Structure
+
+Before populating a template, familiarize yourself with its existing layout to ensure data is entered in the correct locations and formulas remain intact.
+
+**Identifying Row Structure**
+- Locate the model title at top of each tab
+- Identify section headers and their visual separation
+- Find the units row indicating $ millions, %, x, etc.
+- Note column headers distinguishing Actuals vs. Estimates periods
+- Confirm period labels (e.g., FY2024A, FY2025E)
+- Identify input cells vs. formula cells (typically distinguished by font color)
+
+**Identifying Column Structure**
+- Confirm line item labels in leftmost column
+- Verify historical years precede projection years
+- Note the visual border separating historical from projected periods
+- Check for consistent column order across all tabs
+
+**Working with Named Ranges**
+Templates often use named ranges for key inputs and outputs. Before entering data:
+- Review existing named ranges in the template (Formulas → Name Manager in Excel)
+- Common named ranges include: Revenue growth rates, cost percentages, key outputs (Net Income, EBITDA, Total Debt, Cash), scenario selector cell
+- Ensure inputs are entered in cells that feed into these named ranges
+
+### Projection Period
+- Templates typically project 5 years forward from last historical year
+- Verify historical (A) vs. projected (E) columns are clearly separated
+- Confirm columns use fiscal year notation (e.g., FY2024A, FY2025E)
+
+## Margin Analysis
+
+**Note: The following margin analysis should only be performed if prompted by the user or if the template explicitly requires it. If no prompt is given, skip this section.**
+
+Calculate and display profitability margins on the Income Statement (IS) tab to track operational efficiency and enable peer comparison.
+
+### Core Margins to Include
+
+| Margin | Formula | What It Measures |
+|--------|---------|------------------|
+| Gross Margin | Gross Profit / Revenue | Pricing power, production efficiency |
+| EBITDA Margin | EBITDA / Revenue | Core operating profitability |
+| EBIT Margin | EBIT / Revenue | Operating profitability after D&A |
+| Net Income Margin | Net Income / Revenue | Bottom-line profitability |
+
+### Income Statement Layout with Margins
+
+Display margin percentages directly below each profit line item:
+- Gross Margin % below Gross Profit
+- EBIT Margin % below EBIT
+- EBITDA Margin % below EBITDA
+- Net Income Margin % below Net Income
+
+## Credit Metrics
+
+**Note: The following Credit analysis should only be performed if prompted by the user or if the template explicitly requires it. If no prompt is given, skip this section.**
+
+Calculate and display credit/leverage metrics on the Balance Sheet (BS) tab to assess financial health, debt capacity, and covenant compliance.
+
+### Core Credit Metrics to Include
+
+| Metric | Formula | What It Measures |
+|--------|---------|------------------|
+| Total Debt / EBITDA | Total Debt / LTM EBITDA | Leverage multiple |
+| Net Debt / EBITDA | (Total Debt - Cash) / LTM EBITDA | Leverage net of cash |
+| Interest Coverage | EBITDA / Interest Expense | Ability to service debt |
+| Debt / Total Cap | Total Debt / (Total Debt + Equity) | Capital structure |
+| Debt / Equity | Total Debt / Total Equity | Financial leverage |
+| Current Ratio | Current Assets / Current Liabilities | Short-term liquidity |
+| Quick Ratio | (Current Assets - Inventory) / Current Liabilities | Immediate liquidity |
+
+### Credit Metric Hierarchy Checks
+
+Validate that Upside shows strongest credit profile:
+- Leverage: Upside < Base < Downside (lower is better)
+- Coverage: Upside > Base > Downside (higher is better)
+- Liquidity: Upside > Base > Downside (higher is better)
+
+### Covenant Compliance Tracking
+
+If debt covenants are known, add explicit compliance checks comparing actual metrics to covenant thresholds.
+
+## Scenario Analysis (Base / Upside / Downside)
+
+Use a scenario toggle (dropdown) in the Assumptions tab with CHOOSE or INDEX/MATCH formulas.
+
+| Scenario | Description |
+|----------|-------------|
+| Base Case | Management guidance or consensus estimates |
+| Upside Case | Above-guidance growth, margin expansion |
+| Downside Case | Below-trend growth, margin compression |
+
+**Key Drivers to Sensitize**: Revenue growth, Gross margin, SG&A %, DSO/DIO/DPO, CapEx %, Interest rate, Tax rate.
+
+**Scenario Audit Checks**: Toggle switches all statements, BS balances in all scenarios, Cash ties out, Hierarchy holds (Upside > Base > Downside for NI, EBITDA, FCF, margins).
+
+## SEC Filings Data Extraction
+
+If the template specifically requires pulling data from SEC filings (10-K, 10-Q), see [references/sec-filings.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance\3-statement-model/references/sec-filings.md) for detailed extraction guidance. This reference is only needed when populating templates with public company data from regulatory filings.
+
+## Completing Model Templates
+
+This section provides general guidance for completing any 3-statement financial model template while preserving existing formulas and ensuring data integrity.
+
+### Step 1: Analyze the Template Structure
+
+Before entering any data, thoroughly review the template to understand its architecture:
+
+**Identify Input vs. Formula Cells**
+- Look for visual cues (font color, cell shading) that distinguish input cells from formula cells
+- Common conventions: Blue font = inputs, Black font = formulas, Green font = links to other sheets
+- Use Excel's Trace Precedents/Dependents (Formulas → Trace Precedents) to understand cell relationships
+- Check for named ranges that may control key inputs (Formulas → Name Manager)
+
+**Map the Template's Flow**
+- Identify which tabs feed into others (e.g., Assumptions → IS → BS → CF)
+- Note any supporting schedules and their linkages to main statements
+- Document the template's specific line items and structure before populating
+
+### Step 2: Filling in Data Without Breaking Formulas
+
+**Golden Rules for Data Entry**
+
+| Rule | Description |
+|------|-------------|
+| Only edit input cells | Never overwrite cells containing formulas unless intentionally replacing the formula |
+| Preserve cell references | When copying data, use Paste Values (Ctrl+Shift+V) to avoid overwriting formulas with source formatting |
+| Match the template's units | Verify if template uses thousands, millions, or actual values before entering data |
+| Respect sign conventions | Follow the template's existing sign convention (e.g., expenses as positive or negative) |
+| Check for circular references | If the template uses iterative calculations, ensure Enable Iterative Calculation is turned on |
+
+**Safe Data Entry Process**
+1. Identify the exact cells designated for input (usually highlighted or labeled)
+2. Enter historical data first, then verify formulas are calculating correctly for those periods
+3. Enter assumption drivers that feed forecast calculations
+4. Review calculated outputs to confirm formulas are working as intended
+5. If a formula cell must be modified, document the original formula before making changes
+
+**Handling Pre-Built Formulas**
+- If formulas reference cells you haven't populated yet, expect temporary errors (#REF!, #DIV/0!) until all inputs are complete
+- When formulas produce unexpected results, trace precedents to identify missing or incorrect inputs
+- Never delete rows/columns without checking for formula dependencies across all tabs
+
+### Step 3: Validating Formulas
+
+**Formula Integrity Checks**
+
+Before relying on template outputs, validate that formulas are functioning correctly:
+
+| Check Type | Method |
+|------------|--------|
+| Trace precedents | Select a formula cell → Formulas → Trace Precedents to verify it references correct inputs |
+| Trace dependents | Verify key inputs flow to expected output cells |
+| Evaluate formula | Use Formulas → Evaluate Formula to step through complex calculations |
+| Check for hardcodes | Projection formulas should reference assumptions, not contain hardcoded values |
+| Test with known values | Input simple test values to verify formulas produce expected results |
+| Cross-tab consistency | Ensure the same formula logic applies across all projection periods |
+
+**Common Formula Issues to Watch For**
+- Mixed absolute/relative references causing incorrect results when copied across periods
+- Broken links to external files or deleted ranges (#REF! errors)
+- Division by zero in early periods before revenue ramps (#DIV/0! errors)
+- Circular reference warnings (may be intentional for interest calculations)
+- Inconsistent formulas across projection columns (use Ctrl+\ to find differences)
+
+**Validating Cross-Tab Linkages**
+- Confirm values that appear on multiple tabs are linked (not duplicated)
+- Verify schedule totals tie to corresponding line items on main statements
+- Check that period labels align across all tabs
+
+### Step 4: Quality Checks by Sheet
+
+Perform these validation checks on each sheet after populating the template:
+
+**Income Statement (IS) Quality Checks**
+- Revenue figures match source data for historical periods
+- All expense line items sum to reported totals
+- Subtotals (Gross Profit, EBIT, EBT, Net Income) calculate correctly
+- Tax calculation logic is appropriate (handles losses correctly)
+- Forecast drivers reference assumptions tab (no hardcodes)
+- Period-over-period changes are directionally reasonable
+
+**Balance Sheet (BS) Quality Checks**
+- Assets = Liabilities + Equity for every period (primary check)
+- Cash balance matches Cash Flow Statement ending cash
+- Working capital accounts tie to supporting schedules (if applicable)
+- Retained Earnings rolls forward correctly: Prior RE + Net Income - Dividends +/- Adjustments = Ending RE
+- Debt balances tie to debt schedule (if applicable)
+- All balance sheet items have appropriate signs (assets positive, most liabilities positive)
+
+**Cash Flow Statement (CF) Quality Checks**
+- Net Income at top of CFO matches Income Statement Net Income
+- Non-cash add-backs (D&A, SBC, etc.) tie to their source schedules/statements
+- Working capital changes have correct signs (increase in asset = use of cash = negative)
+- CapEx ties to PP&E schedule or fixed asset roll-forward
+- Financing activities tie to changes in debt and equity accounts on BS
+- Ending Cash matches Balance Sheet Cash
+- Beginning Cash equals prior period Ending Cash
+
+**Supporting Schedule Quality Checks**
+- Opening balances equal prior period closing balances
+- Roll-forward logic is complete (Beginning + Additions - Deductions = Ending)
+- Schedule totals tie to main statement line items
+- Assumptions used in calculations match Assumptions tab
+
+### Step 5: Cross-Statement Integrity Checks
+
+After validating individual sheets, confirm the three statements are properly integrated:
+
+| Check | Formula | Expected Result |
+|-------|---------|-----------------|
+| Balance Sheet Balance | Assets - Liabilities - Equity | = 0 |
+| Cash Tie-Out | CF Ending Cash - BS Cash | = 0 |
+| Net Income Link | IS Net Income - CF Starting Net Income | = 0 |
+| Retained Earnings | Prior RE + NI - Dividends - BS Ending RE | = 0 (adjust for SBC/other items as needed) |
+
+### Step 6: Final Review
+
+Before considering the model complete:
+- Toggle through all scenarios (if applicable) to verify checks pass in each case
+- Review all #REF!, #DIV/0!, #VALUE!, and #NAME? errors and resolve or document
+- Confirm all input cells have been populated (search for placeholder values)
+- Verify units are consistent across all tabs
+- Save a clean version before making any additional modifications
+
+## Model Validation and Audit
+
+This section consolidates all validation checks and audit procedures for completed templates.
+
+### Core Linkages (Must Always Hold)
+
+See [references/formulas.md](https://github.com/NousResearch/hermes-agent/blob/main/optional-skills/finance\3-statement-model/references/formulas.md) for all formula details.
+
+| Check | Formula | Expected Result |
+|-------|---------|-----------------|
+| Balance Sheet Balance | Assets - Liabilities - Equity | = 0 |
+| Cash Tie-Out | CF Ending Cash - BS Cash | = 0 |
+| Cash Monthly vs Annual | Closing Cash (Monthly) - Closing Cash (Annual) | = 0 |
+| Net Income Link | IS Net Income - CF Starting Net Income | = 0 |
+| Retained Earnings | Prior RE + NI + SBC - Dividends - BS Ending RE | = 0 |
+| Equity Financing | ΔCommon Stock/APIC (BS) - Equity Issuance (CFF) | = 0 |
+| Year 0 Equity | Equity Raised (Year 0) - Beginning Equity Capital (Year 1) | = 0 |
+
+### Sign Convention Reference
+
+| Statement | Item | Sign Convention |
+|-----------|------|-----------------|
+| CFO | D&A, SBC | Positive (add-back) |
+| CFO | ΔAR (increase) | Negative (use of cash) |
+| CFO | ΔAP (increase) | Positive (source of cash) |
+| CFI | CapEx | Negative |
+| CFF | Debt issuance | Positive |
+| CFF | Debt repayments | Negative |
+| CFF | Dividends | Negative |
+
+### Circular Reference Handling
+
+Interest expense creates circularity: Interest → Net Income → Cash → Debt Balance → Interest
+
+Enable iterative calculation in Excel: File → Options → Formulas → Enable iterative calculation. Set maximum iterations to 100, maximum change to 0.001. Add a circuit breaker toggle in Assumptions tab.
+
+### Check Categories
+
+**Section 1: Currency Consistency**
+- Currency identified and documented in Assumptions
+- All tabs use consistent currency symbol and scale
+- Units row matches model currency
+
+**Section 2: Balance Sheet Integrity**
+- Assets = Liabilities + Equity (for each period)
+- Formula: Assets - Liabilities - Equity (must = 0)
+
+**Section 3: Cash Flow Integrity**
+- Cash ties to BS (CF Ending Cash = BS Cash)
+- Cash Monthly vs Annual: Closing Cash (Monthly) = Closing Cash (Annual)
+- NI ties to IS (CF Net Income = IS Net Income)
+- D&A ties to schedule
+- SBC ties to IS
+- ΔAR, ΔInventory, ΔAP tie to WC schedule
+- CapEx ties to DA schedule
+
+**Section 4: Retained Earnings**
+- RE roll-forward check: Prior RE + NI + SBC - Dividends = Ending RE
+- Show component breakdown for debugging
+
+**Section 5: Working Capital**
+- AR, Inventory, AP tie to BS
+- DSO, DIO, DPO reasonability checks (flag if outside normal ranges)
+
+**Section 6: Debt Schedule**
+- Total Debt ties to BS (Current + LT Debt)
+- Interest calculation ties to IS
+
+**Section 6b: Equity Financing**
+- Equity issuance proceeds tie to BS Common Stock/APIC increase
+- Cash increase from equity = Equity account increase (must balance)
+- Equity Raise Tie-Out: ΔCommon Stock/APIC (BS) = Equity Issuance (CFF) (must = 0)
+- Year 0 Equity Tie-Out: Equity Raised (Year 0) = Beginning Equity Capital (Year 1)
+
+**Section 6c: NOL Schedule**
+- Beginning NOL (Year 1 / Formation) = 0 (new business starts with zero NOL)
+- NOL increases only when EBT < 0 (losses must be realized to generate NOL)
+- DTA ties to BS (NOL Schedule DTA = BS Deferred Tax Asset)
+- NOL utilization ≤ 80% of EBT (post-2017 federal limitation)
+- NOL balance is non-negative (cannot utilize more than available)
+- NOL generated only when EBT < 0
+- Tax expense = 0 when taxable income ≤ 0
+
+**Section 7: Scenario Hierarchy**
+- Absolute metrics: Upside > Base > Downside (NI, EBITDA, FCF)
+- Margins: Upside > Base > Downside (GM%, EBITDA%, NI%)
+- Credit metrics: Upside < Base < Downside for leverage (inverted)
+
+**Section 8: Formula Integrity**
+- COGS, S&M, G&A, R&D, SBC driven by % of Revenue (no hardcodes)
+- Consistent formulas across projection years
+- No #REF!, #DIV/0!, #VALUE! errors
+
+**Section 9: Credit Metric Thresholds**
+- Flag metrics as Green/Yellow/Red based on covenant thresholds
+- Summary of any red flags
+
+### Master Check Formula
+
+Aggregate all section statuses into a single master check:
+- If all sections pass → "✓ ALL CHECKS PASS"
+- If any section fails → "✗ ERRORS DETECTED - REVIEW BELOW"
+
+### Quick Debug Workflow
+
+When Master Status shows errors:
+1. Scroll to find red-highlighted sections
+2. Identify which check category has failures
+3. Navigate to source tab to investigate
+4. Fix the underlying issue
+5. Return to Checks tab to verify resolution
+
+
+## Data sources — MCP first, web fallback
+
+Many passages below say "use the S&P Kensho MCP / Daloopa MCP / FactSet MCP". Those are commercial financial-data MCPs from the original Cowork plugin context. In Hermes:
+
+- **If you have any structured financial-data MCP configured** (Hermes supports MCP — see `native-mcp` skill), prefer it for point-in-time comps, precedent transactions, and filings.
+- **Otherwise**, fall back to:
+  - `web_search` / `web_extract` against SEC EDGAR (`https://www.sec.gov/cgi-bin/browse-edgar`) for US filings
+  - Company IR pages for press releases, earnings decks
+  - `browser_navigate` for interactive data portals
+  - User-provided data (explicitly ask when the context doesn't have it)
+- **Never fabricate**. If a multiple, precedent, or filing number can't be sourced, flag the cell as `[UNSOURCED]` and surface it to the user.
+
+## Attribution
+
+This skill is adapted from Anthropic's Claude for Financial Services plugin suite (Apache-2.0). The Office-JS / Cowork live-Excel paths have been removed; this version targets headless openpyxl via the `excel-author` skill's conventions. Original: https://github.com/anthropics/financial-services