@v587d/capital-generation 2.7.7 → 2.7.9

package/selected-skills/financeskills/skills/statement-preparation/references/accruals-deferrals.md

@@ -0,0 +1,24 @@
+# Accruals and Deferrals
+
+## The Four Period-End Adjustment Types
+| Type | Cash vs. Recognition | Example | Entry |
+|---|---|---|---|
+| Accrued expense | Expense before cash out | Unbilled legal fees | Dr Expense / Cr Accrued Liability |
+| Accrued revenue | Revenue before cash in | Unbilled services delivered | Dr Accrued Receivable / Cr Revenue |
+| Deferred (prepaid) expense | Cash out before expense | Annual insurance premium | Dr Prepaid Asset at payment; amortize Dr Expense / Cr Prepaid |
+| Deferred revenue | Cash in before revenue | Annual SaaS subscription billed upfront | Dr Cash / Cr Deferred Revenue; release Dr Deferred Revenue / Cr Revenue |
+
+## Estimation Standards for Accruals
+- Base on invoices received post-close, PO/GRNI reports, contracts, and run-rates.
+- Document the basis; an accrual without support fails audit.
+- Reverse auto-reversing accruals on day 1 of the next period; true-up against actuals and track accrual accuracy (target: |true-up| < 5% of accrual).
+
+## Cut-Off Rules
+- Goods: recognize when control transfers (shipping terms — FOB shipping point vs. destination).
+- Services: recognize as performed, supported by timesheets/completion evidence.
+- Three-way match exceptions at close → GRNI accrual.
+
+## Red Flags
+- Accruals flat period-over-period (stale, not re-estimated).
+- Deferred revenue declining while billings grow (release schedule error).
+- Round-number accruals with no support.

package/selected-skills/financeskills/skills/statement-preparation/references/cash-flow-method.md

@@ -0,0 +1,32 @@
+# Cash Flow Statement: Indirect Method
+
+## Structure (IAS 7 / ASC 230)
+1. **Operating**: Start with net income, add back non-cash items, adjust for working capital deltas.
+2. **Investing**: Capex, acquisitions, asset disposals, investment purchases/sales.
+3. **Financing**: Debt draws/repayments, equity issues/buybacks, dividends, lease principal (IFRS 16).
+
+## Operating Section Walk
+```
+Net Income
++ Depreciation & Amortization
++ Impairment losses
++ Share-based compensation
++/- Deferred tax expense/(benefit)
++/- Loss/(gain) on asset disposal
+- Increase in receivables      (+ if decrease)
+- Increase in inventory        (+ if decrease)
++ Increase in payables         (- if decrease)
++ Increase in deferred revenue (- if decrease)
+= Cash Flow from Operations
+```
+
+## Classification Traps
+- **Interest paid**: Operating under US GAAP; operating OR financing under IFRS (be consistent).
+- **Interest/dividends received**: Operating (US GAAP); operating or investing (IFRS).
+- **Lease payments (IFRS 16)**: Principal → financing; interest → per interest policy.
+- **Capitalized development costs**: Investing, not operating.
+
+## Tie-Out Checks
+1. Net change in cash = closing cash − opening cash (including FX effect line).
+2. D&A added back must equal D&A in the fixed asset rollforward.
+3. Working capital deltas must reconcile to balance sheet movements net of acquisitions/FX (non-cash portions excluded).

package/selected-skills/financeskills/skills/tax-efficient-investing/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - tax-efficient-investing
+
+## Ask
+
+> I'm in the 24% federal tax bracket, single filer, earning $95,000. I have a 401k at work with a 4% employer match, and I have $10,000 to invest this year. How should I allocate it across account types for maximum tax efficiency?
+
+## What a correct response contains
+
+Should first confirm whether the user is capturing the full employer 4% match (free money). Should recommend: (1) contribute enough to 401k to get full match, (2) max Roth IRA ($7,000 for 2024), (3) remaining into 401k or taxable brokerage. Should calculate the tax savings from pre-tax 401k contributions. Should explain Roth vs. traditional trade-off at 24% bracket.
+
+## File-driven variant
+
+With fixture `evals/files/tax_inputs.csv`:
+
+> From the attached tax inputs (evals/files/tax_inputs.csv), calculate the after-tax future value of $10,000 invested in a taxable account vs. a Roth IRA over 25 years at 7% gross return. Quantify the tax drag in dollar terms.
+
+Expected: Roth IRA FV $54,274 (no tax drag); Taxable FV $42,415 (15% tax on gains applied annually); tax drag cost $11,859 over 25 years; Roth advantage: 21.8% more wealth.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) — import its functions rather than doing arithmetic in prose.

package/selected-skills/financeskills/skills/tax-efficient-investing/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: tax-efficient-investing
+description: When the user wants to invest in a tax-efficient way, maximise contributions to tax-advantaged accounts, understand the tax drag on investment returns, compare traditional vs. Roth accounts, or determine the optimal account to hold specific asset classes. Also use when the user mentions "401k vs Roth," "ISA allowance," "tax on investments," "asset location," "tax-loss harvesting," or "after-tax returns."
+metadata:
+  version: 1.0.0
+---
+
+# Tax-Efficient Investing
+
+You are a Tax-Aware Investment Advisor. Your goal is to help the user legally minimise their tax burden on investments so more of their wealth compounds over time.
+
+## Initial Assessment
+
+1. **Tax Situation**
+   - Current marginal income tax rate and capital gains tax rate.
+   - Country/jurisdiction (US 401k/IRA/Roth, UK ISA/SIPP, other).
+   - Filing status (single, married filing jointly, etc.).
+
+2. **Account Inventory**
+   - Existing tax-advantaged accounts and current balances.
+   - Annual contribution room remaining.
+   - Taxable brokerage accounts and unrealised gains/losses.
+
+3. **Investment Goals**
+   - Time horizon and target asset allocation.
+   - Expected investment return and income needs.
+
+---
+
+## Tax-Efficiency Framework
+
+### Priority Order (US context — adapt for other jurisdictions)
+1. **Employer match** — contribute enough to the 401(k) to capture the full match (100% instant return).
+2. **HSA** (if eligible) — triple tax advantage: deductible contributions, tax-free growth, tax-free withdrawals for medical.
+3. **Max Roth IRA** — tax-free growth and withdrawals; best for those expecting higher future tax rates.
+4. **Max 401(k)** — pre-tax contributions reduce current taxable income.
+5. **Taxable brokerage** — use remaining savings here with tax-efficient funds (index funds, ETFs, municipal bonds).
+
+### Asset Location Strategy
+Place the least tax-efficient assets in tax-advantaged accounts:
+- **In tax-advantaged**: REITs, bonds, high-dividend stocks, actively managed funds.
+- **In taxable**: broad index funds, ETFs, municipal bonds, long-term buy-and-hold equities.
+
+### Tax-Loss Harvesting
+Realise capital losses to offset capital gains, reducing current-year tax liability. Replace with a similar (not substantially identical) fund to maintain exposure.
+
+---
+
+## Technical Concepts
+
+### Tax Drag
+The reduction in annual return caused by taxes on dividends, interest, and realised capital gains.
+`After-Tax Return = Gross Return × (1 − Tax Rate on Gains)`
+
+### Tax-Equivalent Yield
+Converts a tax-free yield into its taxable equivalent for comparison:
+`Tax-Equivalent Yield = Tax-Free Yield / (1 − Marginal Tax Rate)`
+
+### Roth vs. Traditional Break-Even
+Roth is better if future marginal tax rate > current marginal tax rate.
+Traditional is better if future marginal tax rate < current marginal tax rate.
+
+---
+
+## Output Format
+
+**Account Priority Plan**
+- Ranked contribution order with dollar amounts for the current tax year.
+- Remaining contribution room per account.
+
+**Asset Location Map**
+- Which holdings belong in which account type and why.
+
+**Tax Drag Analysis**
+- Estimated annual after-tax return vs. gross return under current structure.
+- Projected 10/20/30-year wealth difference between tax-efficient and tax-inefficient approach.
+
+**Action Items**
+- Specific rebalancing or contribution changes to implement.
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Deterministic functions for this skill's core computations. Run `python3 scripts/calculate.py` to self-test; import the functions instead of doing mental math.
+
+---
+
+## References
+- [Account Types Guide](./references/account-types.md): Overview of US and international tax-advantaged account types, limits, and rules.
+- [Asset Location Research](./references/asset-location.md): Evidence on the value of asset location and tax-loss harvesting strategies.
+
+---
+
+## Related Skills
+- **retirement-planning**: Retirement accounts are the primary tax-efficient vehicle — coordinate contribution strategy.
+- **tax-planning**: Coordinate investment tax strategy with broader income tax planning.
+- **investment-analysis**: Evaluate the after-tax return of specific investment options.

package/selected-skills/financeskills/skills/tax-efficient-investing/references/account-types.md

@@ -0,0 +1,33 @@
+# Account Types Guide
+
+## United States
+
+### Tax-Deferred Accounts (Pay tax on withdrawal)
+| Account | Who | 2024 Limit | Key Rule |
+|---|---|---|---|
+| Traditional 401(k) | Employees | $23,000 (+$7,500 catch-up) | RMDs at age 73 |
+| Traditional IRA | Anyone with earned income | $7,000 (+$1,000 catch-up) | Deductibility phases out with 401k |
+| SEP-IRA | Self-employed | 25% of comp, max $69,000 | No catch-up |
+| SIMPLE IRA | Small business | $16,000 (+$3,500 catch-up) | 2-year vesting rule |
+
+### Tax-Free Accounts (Pay tax now, withdraw tax-free)
+| Account | Who | 2024 Limit | Key Rule |
+|---|---|---|---|
+| Roth 401(k) | Employees | Same as 401(k) | No RMDs |
+| Roth IRA | Income limit applies | $7,000 (+$1,000 catch-up) | Phases out at $146k–$161k (single) |
+| HSA | HDHP enrollees | $4,150 individual / $8,300 family | Triple tax advantage |
+
+### Taxable Brokerage
+No contribution limits. Gains taxed at capital gains rates (0%, 15%, or 20% federal depending on income). Qualified dividends also receive preferential rates.
+
+## United Kingdom
+| Account | Annual Allowance | Tax Treatment |
+|---|---|---|
+| ISA | £20,000 | Tax-free growth and withdrawals |
+| SIPP | £60,000 (annual allowance) | Tax-relieved contributions, taxed on withdrawal |
+| Lifetime ISA | £4,000 (25% bonus) | First home or retirement only |
+
+## General Principles (All Jurisdictions)
+1. Maximise employer-matched accounts first (free money).
+2. Prefer tax-free over tax-deferred if future tax rate expected to rise.
+3. Use taxable accounts last, with the most tax-efficient instruments (index ETFs, munis).

package/selected-skills/financeskills/skills/tax-efficient-investing/references/asset-location.md

@@ -0,0 +1,36 @@
+# Asset Location Research
+
+Asset location is the strategy of placing investments in the account type that minimises their tax cost.
+
+## Core Principle
+Different assets generate different types of taxable events:
+- **Interest income** (bonds, CDs): taxed as ordinary income — highest rate.
+- **Dividends**: qualified dividends taxed at capital gains rates; non-qualified at ordinary rates.
+- **Capital gains**: long-term gains taxed at preferential rates (0/15/20%); short-term at ordinary rates.
+- **REIT distributions**: mostly ordinary income — high tax cost.
+
+## Optimal Asset Location
+
+| Asset Class | Best Account | Reason |
+|---|---|---|
+| Bonds / Fixed income | Tax-advantaged (traditional) | Interest taxed as ordinary income |
+| REITs | Tax-advantaged | High ordinary income distributions |
+| High-dividend stocks | Tax-advantaged | Avoids annual dividend tax |
+| Actively managed funds | Tax-advantaged | High turnover generates short-term gains |
+| Broad index funds / ETFs | Taxable | Low turnover, qualified dividends, tax-loss harvesting |
+| Municipal bonds | Taxable | Already tax-exempt; wasted in tax-advantaged |
+| International stocks | Taxable | Foreign tax credit only available in taxable accounts |
+
+## Tax-Loss Harvesting
+Selling a position at a loss to realise the loss for tax purposes, then immediately buying a similar (but not "substantially identical") fund to maintain market exposure.
+
+**Annual value**: Studies estimate 0.5–1.5% of portfolio value per year in tax alpha for taxable accounts with sufficient volatility and size (Vanguard, 2015).
+
+**Wash-sale rule (US)**: Cannot repurchase the same or substantially identical security within 30 days before or after the sale.
+
+## Quantified Value of Asset Location
+Vanguard research (Jaconetti et al., 2018) estimates optimal asset location adds 0–0.75% per year in after-tax returns, depending on tax bracket and asset mix. The benefit is greatest for investors in high tax brackets with significant bond allocations.
+
+## Sources
+- Jaconetti, C., Kinniry, F., & Schlanger, T. (2018). *Vanguard's Principles for Investing Success*.
+- Kitces, M. (2015). *The Asset Location Decision for Optimal After-Tax Returns*. Kitces.com.

package/selected-skills/financeskills/skills/tax-planning/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - tax-planning
+
+## Ask
+
+> I'm a freelancer making $150k/year. I'm currently a sole proprietor. Am I paying too much in tax?
+
+## What a correct response contains
+
+Should identify the potential benefit of an S-Corp election (to save on self-employment tax). Should discuss common deductions for freelancers. Should emphasize that AI cannot file taxes and a CPA review is required. Should provide a Tax Strategy Report structure with an action plan.
+
+## File-driven variant
+
+With fixture(s) `evals/files/income_and_brackets.csv`:
+
+> Using the attached bracket schedule and income (evals/files/income_and_brackets.csv): compute total tax, effective rate, and marginal rate. Then quantify the PV benefit of deferring $100,000 of that tax by 3 years at a 10% discount rate.
+
+Expected: Tax $308,000; effective 15.4%; marginal 21%; deferral PV benefit $24,869.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) - import its functions rather than doing arithmetic in prose.

package/selected-skills/financeskills/skills/tax-planning/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: tax-planning
+description: When the user wants to optimize tax liability or ensure tax compliance. Also use when the user mentions "tax strategy," "lowering taxes," "tax credits," "deductions," "filing prep," "corporate tax," "VAT audit," or "capital gains planning." Use this for both individual and corporate tax.
+metadata:
+  version: 1.1.0
+---
+
+# Tax Planning
+
+You are a Tax Strategist. Your goal is to maximize after-tax wealth by leveraging legal tax credits, deductions, and structural optimizations while ensuring full compliance.
+
+## Initial Assessment
+
+1. **Tax Jurisdiction**
+   - Which country and local region?
+   - Is there a tax treaty involved (for international entities)?
+
+2. **Entity Type**
+   - Individual, Sole Proprietorship, LLC, S-Corp, or C-Corp?
+   - What is the estimated annual income?
+
+3. **Existing Documentation**
+   - Previous year's tax returns.
+   - Current year's income/expense logs.
+
+---
+
+## Tax Optimization Framework
+
+### Compliance Limitation
+
+**AI cannot file tax returns.**
+This skill is for strategy and automation of calculations. All final tax filings must be prepared or reviewed by a qualified CPA or tax attorney.
+
+### Priority Order
+1. **Compliance Verification** (Ensuring all basic filings are up to date).
+2. **Deduction Identification** (Expensing all eligible business costs).
+3. **Credit Analysis** (Finding dollar-for-dollar tax reductions like R&D credits).
+4. **Structural Optimization** (Is the entity type the most tax-efficient?).
+5. **Deferral Strategies** (Timing income and expenses to lower current liability).
+
+---
+
+## Technical Tax Steps
+
+### 1. Categorization Audit
+- Review expense logs to ensure all deductible items are captured (Travel, Meals, Equipment).
+- Identify Section 179 depreciation opportunities for capital assets.
+
+### 2. Credit Screening
+- Screen for industry-specific credits (Energy, R&D, Opportunity Zones).
+
+### 3. Deferral Modeling
+- Compare the impact of contributing to deferred tax accounts (401k, SEP IRA) vs. taxable accounts.
+
+---
+
+## Output Format
+
+### Tax Strategy Report Structure
+
+**Executive Summary**
+- Estimated Baseline Liability.
+- Potential Optimized Liability.
+- Total Estimated Savings.
+
+**Strategy Details**
+- **Deductions**: List of additional eligible expenses found.
+- **Credits**: Specific tax credits for which the entity qualifies.
+- **Structural**: Recommendations for entity type or income timing changes.
+
+**Action Plan**
+1. Immediate record-keeping improvements.
+2. Timing-specific actions (e.g., "Purchase equipment before Dec 31").
+3. Items for CPA review.
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Deterministic functions for this skill's core computations. Run `python3 scripts/calculate.py` to self-test; import the functions instead of doing mental math.
+
+---
+
+## References
+- [IRS / Local Tax Codes](./references/tax-code-lookup.md): Direct links to source regulations.
+- [Deduction Cheat Sheet](./references/common-deductions.md): List of standard eligible expenses.
+
+---
+
+## Related Skills
+- **financial-analysis**: To audit the income data used for tax planning.
+- **budget-forecast**: To project future tax liabilities.
+- **audit-checklist**: To ensure tax-related internal controls are sound.

package/selected-skills/financeskills/skills/tax-planning/references/common-deductions.md

@@ -0,0 +1,28 @@
+# Common Deductions: Business Expense Guide
+
+A checklist of standard eligible expenses that can lower a business's taxable income.
+
+## 🏛️ Standard Categories
+
+### 1. Operations
+- **Rent/Lease**: Office space or equipment rentals.
+- **Utilities**: Electricity, water, internet, and phone.
+- **Supplies**: Office consumables, software subscriptions (SaaS).
+
+### 2. Marketing & Travel
+- **Advertising**: Online ads, agency fees, print materials.
+- **Travel**: 100% of transport; percentage of meals (varies by year/jurisdiction).
+
+### 3. Personnel
+- **Salaries**: W-2 wages and employer-side payroll taxes.
+- **Benefits**: Health insurance premiums, retirement contributions.
+
+---
+
+## 🔍 Special Deductions
+- **Section 179 (US)**: Immediate expensing of the full purchase price of qualifying equipment.
+- **R&D Credits**: Dollar-for-dollar tax reductions for innovative activities.
+
+## 🔗 Sources
+- [IRS: Deducting Business Expenses](https://www.irs.gov/businesses/small-businesses-self-employed/deducting-business-expenses)
+- [HMRC: Expenses if you're self-employed](https://www.gov.uk/expenses-if-youre-self-employed)

package/selected-skills/financeskills/skills/tax-planning/references/tax-code-lookup.md

@@ -0,0 +1,25 @@
+# Tax Code Lookup: Global Sources
+
+Directories and portals for accessing the most up-to-date tax laws and regulations.
+
+## 🏛️ Major Portals
+
+### United States
+- **IRS (Internal Revenue Service)**: [Official Website](https://www.irs.gov/). Use the "Search" function for specific Publication numbers (e.g., Pub 535 for Business Expenses).
+
+### South Africa
+- **SARS (South African Revenue Service)**: [Official Website](https://www.sars.gov.za/). Key link: [Legal Counsel / Primary Legislation](https://www.sars.gov.za/legal-counsel/primary-legislation/).
+
+### United Kingdom
+- **HMRC (HM Revenue & Customs)**: [Official Manuals](https://www.gov.uk/government/organisations/hm-revenue-customs/about/publications).
+
+---
+
+## 🔍 Best Practices for Searching
+1.  **Check the Year**: Tax laws change annually. Ensure you are looking at the code for the correct filing year.
+2.  **Verify Status**: Ensure a regulation is "In Effect" and hasn't been repealed or superseded.
+3.  **Jurisdiction Check**: Confirm if state/provincial laws override or supplement federal laws.
+
+## 🔗 Sources
+- [OECD: Tax Database](https://www.oecd.org/tax/tax-policy/tax-database/)
+- [IBFD: International Bureau of Fiscal Documentation](https://www.ibfd.org/)

package/selected-skills/financeskills/skills/three-statement-modeling/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - three-statement-modeling
+
+## Ask
+
+> Build a simple 3-year integrated model: revenue 1,000 growing 10%, EBITDA margin 25%, D&A 50/yr (capex 60/yr), tax 30%, DSO 45, DPO 30, DIO 0, opening cash 100, no debt, no dividends. Show the three statements and prove the balance sheet balances.
+
+## What a correct response contains
+
+A coded model producing IS (NI year 1 = (250-50)x0.7 = 140), WC schedule from days, CFS deriving cash, BS with explicit balance check = 0 all years.
+
+## File-driven variant
+
+With fixture(s) `evals/files/model_inputs.xlsx`:
+
+> Project one year of the linked three-statement model from the attached workbook (evals/files/model_inputs.xlsx): income statement down to net income, cash rollforward, PP&E rollforward, and PROVE the balance sheet balances (assets = liabilities + equity).
+
+Expected: Revenue 110.0; net income 13.16; closing cash 26.80; PP&E 81.10; equity 67.90; balance check passes.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) - import its functions rather than doing arithmetic in prose.

package/selected-skills/financeskills/skills/three-statement-modeling/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: three-statement-modeling
+description: When the user wants to build an integrated financial model linking income statement, balance sheet, and cash flow. Also use when the user mentions "3-statement model," "integrated model," "balance sheet doesn't balance," "circular reference," "revolver plug," "model drivers," or "financial projections."
+metadata:
+  version: 1.0.0
+---
+
+# Three-Statement Modeling
+
+You are a Financial Modeler. Your goal is to build (or debug) an integrated model where the three statements link correctly, the balance sheet balances by construction, and every output traces to a labeled driver.
+
+## Initial Assessment
+
+1. **Purpose & Horizon**
+   - Budgeting, valuation feed (company-valuation), debt capacity (credit-analysis), or scenario planning — purpose sets granularity.
+   - Monthly (operational, ≤ 24 months) vs. annual (strategic, 5+ years).
+
+2. **Starting Point**
+   - Historical statements (≥ 3 years) for ratio calibration; opening balance sheet that actually balances.
+
+---
+
+## Modeling Framework
+
+### Build Order (always)
+1. **Drivers & assumptions sheet** — every assumption in ONE place, labeled, with historical context alongside.
+2. **Income statement**: revenue build (price × volume / cohort / segment — never "grow 10%" without basis) → costs (variable as % of revenue, fixed as schedules, stepped where real) → EBITDA → D&A from the asset schedule → interest from the debt schedule → tax → NI.
+3. **Supporting schedules**: PP&E rollforward (capex, depreciation), working capital (DSO/DIO/DPO days driving AR/inventory/AP), debt schedule (draws, amortization, interest), equity rollforward (NI, dividends, issues).
+4. **Balance sheet**: every line driven by a schedule — nothing hardcoded.
+5. **Cash flow statement**: indirect method derived ENTIRELY from IS + BS deltas. Cash from the CFS feeds the BS cash line.
+
+### The Linkages That Make It "Integrated"
+- NI → retained earnings AND CFS top line.
+- D&A: IS expense ↔ PP&E schedule ↔ CFS addback.
+- ΔWC: BS deltas → CFS operating section.
+- Capex: CFS investing ↔ PP&E schedule.
+- Debt draws/repayments: CFS financing ↔ debt schedule ↔ interest on IS.
+- Dividends: equity schedule ↔ CFS financing.
+
+### The Revolver Plug (cash sweep logic)
+`If cash before revolver < minimum cash → draw the shortfall; if excess cash and revolver balance > 0 → repay.` This makes the BS balance by construction and creates the interest↔cash circularity: resolve with opening-balance interest convention (preferred — stable, auditable) or iterative calculation (document it).
+
+### Balance Check Discipline
+`Assets − Liabilities − Equity = 0` displayed on every period, every sheet, conditionally flagged. A model without a visible balance check is untrustworthy by default.
+
+---
+
+## Technical Analysis Steps
+
+1. **Build in the fixed order** (one driver block, then statements, then checks): drivers → statements → checks, with the balance check shown for every period. Nothing here assumes a shell or a spreadsheet engine — write the linkage out, and hand a model long enough to need real compute to the delegated `data_junior`.
+2. **Calibrate**: projected ratios (margins, days, capex/revenue) vs. 3-year history — every divergence from history needs a stated reason.
+3. **Stress the plumbing**: zero out revenue growth, spike capex — does the revolver respond, does the BS still balance, does interest update?
+
+---
+
+## Output Format
+
+### Model Package
+
+**Assumptions Summary**: driver table with historical vs. projected.
+
+**Statements**: IS, BS, CFS with balance check row.
+
+**Schedules**: PP&E, WC, debt, equity rollforwards.
+
+**Diagnostics**: balance check status, revolver utilization, key ratio trajectory, circularity convention stated.
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Deterministic functions for this skill's core computations, kept as reviewable material. This plugin's research role has no shell and the scripts are not part of the installed package, so nothing here runs them: build the linkage line by line from the checks in [Model Integrity Checklist](./references/model-checks.md), show the arithmetic in the answer, and hand anything that needs real compute to the delegated `data_junior`.
+
+---
+
+## References
+- [Model Integrity Checklist](./references/model-checks.md): The full debugging sequence for a model that doesn't balance.
+
+---
+
+## Related Skills
+- **company-valuation**: The DCF consumes this model's FCF.
+- **budget-forecast**: Driver logic for the projections.
+- **credit-analysis**: Covenant and DSCR outputs from the debt schedule.
+- **working-capital-analysis**: The days assumptions driving the WC schedule.

package/selected-skills/financeskills/skills/three-statement-modeling/references/model-checks.md

@@ -0,0 +1,32 @@
+# Model Integrity Checklist
+
+## When the Balance Sheet Doesn't Balance — Debug Sequence
+Work in this order; stop when the imbalance first appears.
+1. **Find the first broken period.** The error is THERE, not where it's biggest (imbalances compound).
+2. **Opening balance sheet**: does period 0 balance? If not, nothing downstream can.
+3. **Retained earnings**: RE_close = RE_open + NI − dividends. The #1 culprit — check NI links to the right period and dividends aren't double-counted.
+4. **Cash**: BS cash must equal CFS ending cash. If CFS is "correct" but BS differs, a BS line moved without a CFS counterpart.
+5. **Delta audit**: for every BS line, ΔBS must appear somewhere in the CFS (or be a documented non-cash move). Build a delta-vs-CFS mapping table — this finds the missing item mechanically.
+6. **Non-cash traps**: PIK interest (IS expense, no cash, adds to debt), unrealized FX on monetary items, asset writeoffs/impairments, capitalized interest, leases commencing (ROU + liability appear with no cash), revaluations (OCI, not CFS).
+7. **Sign conventions**: the eternal ΔWC sign error — AR increase CONSUMES cash (negative in CFS).
+
+## Circularity Management
+Interest → cash → revolver → interest. Options:
+- **Opening balance convention**: interest on opening debt/cash balances. Slight inaccuracy, total stability. Recommended default.
+- **Average balance + iteration**: more precise; in Excel requires iterative calc (risk: silent convergence failures); in Python, loop until |Δinterest| < tolerance.
+- Never mix conventions across tranches.
+
+## Hardcode Hygiene
+- Inputs only on the assumptions sheet.
+- No constants inside formulas.
+- Color convention if spreadsheet-based.
+- One driver block: every statement derives from it, nothing re-typed per schedule.
+
+## Pre-Delivery Test Battery
+1. Balance check = 0 every period.
+2. CFS ending cash = BS cash every period.
+3. Zero-growth test: flat revenue → margins should stay flat; if they drift, a cost is mislinked.
+4. Revolver test: force a cash shortfall → revolver draws; force surplus → repays to zero before cash builds.
+5. Depreciation exhaustion: assets never depreciate below zero/residual.
+6. Ratio reasonableness vs. history: margins, days, capex/revenue, leverage.
+7. Stress symmetry: +10% and −10% revenue should produce roughly mirrored (not wildly asymmetric) outcomes unless steps/breakpoints explain it.

package/selected-skills/financeskills/skills/treasury-management/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - treasury-management
+
+## Ask
+
+> We have $5M in cash but $2M is in Euros and the Euro is dropping. We also have a $1M payroll next week. What should we do?
+
+## What a correct response contains
+
+Should identify the immediate liquidity need (payroll) and the FX risk (Euro dropping). Should suggest a cash positioning review and potential FX hedging or conversion. Should provide a structured Treasury Report with a cash flow forecast and risk management recommendations.
+
+## File-driven variant
+
+With fixture(s) `evals/files/treasury_position.csv`:
+
+> From the attached treasury position (evals/files/treasury_position.csv): compute liquidity runway in days, the 6-month NGN/USD forward rate under covered interest parity, and the NGN cost of hedging the $1,000,000 payable forward versus at spot.
+
+Expected: Runway 80 days; 6m forward 1,624.39 NGN/USD; hedged cost NGN 1,624,390,244 vs spot 1,500,000,000 - forward premium 8.3%.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) - import its functions rather than doing arithmetic in prose.