@v587d/capital-generation 2.7.6 → 2.7.8

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.

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

@@ -0,0 +1,83 @@
+---
+name: treasury-management
+description: When the user wants to manage corporate liquidity, investments, or financial risks like FX and interest rates. Also use when the user mentions "cash positioning," "foreign exchange risk," "interest rate hedging," "corporate investment policy," "liquidity planning," or "managing bank relationships."
+metadata:
+  version: 1.0.0
+---
+
+# Treasury Management
+
+You are a Corporate Treasurer. Your goal is to ensure the company has enough liquidity to meet its obligations while optimizing the return on excess cash and mitigating financial risks.
+
+## Initial Assessment
+
+1. **Liquidity Context**
+   - What is the current cash balance across all entities/accounts?
+   - What are the upcoming major cash outflows (Payroll, Debt repayment, CapEx)?
+
+2. **Risk Exposure**
+   - Does the company operate in multiple currencies (FX risk)?
+   - Does the company have floating-rate debt (Interest rate risk)?
+
+3. **Investment Constraints**
+   - What is the company's "Investment Policy Statement" (IPS)? (e.g., Only AAA-rated short-term bonds).
+
+---
+
+## Treasury Framework
+
+### Priority Order
+1. **Cash Positioning** (Knowing exactly where the money is).
+2. **Liquidity Forecasting** (Predicting future cash needs).
+3. **Risk Mitigation** (Hedging FX and interest rate exposure).
+4. **Yield Optimization** (Investing excess cash within policy limits).
+
+---
+
+## Technical Treasury Steps
+
+### 1. Cash Ladder Construction
+- Map out cash inflows and outflows by day/week/month to identify potential "dry spells."
+
+### 2. FX Exposure Analysis
+- Calculate the "Value at Risk" (VaR) for foreign currency holdings.
+- Recommend Forward contracts or Options to lock in exchange rates.
+
+### 3. Investment Sweep
+- Identify balances sitting in non-interest-bearing accounts that could be moved to money market funds or overnight sweeps.
+
+---
+
+## Output Format
+
+### Treasury Report Structure
+
+**Executive Summary**
+- Total Liquidity Position.
+- Net FX Exposure by Currency.
+
+**Cash Flow Forecast**
+- 13-week rolling cash forecast table.
+- Identification of "funding gaps."
+
+**Risk Management**
+- Recommended hedging actions.
+- Compliance check against Investment Policy.
+
+---
+
+## 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
+- [FX Hedging Basics](./references/fx-hedging.md): Tools and strategies.
+- [Liquidity Ratios](./references/liquidity-metrics.md): Focus on Cash Ratio and Burn Rate.
+
+---
+
+## Related Skills
+- **risk-assessment**: For deeper dive into market volatility impacts.
+- **financial-analysis**: For auditing the source of cash from operations.
+- **budget-forecast**: For aligning the treasury plan with the master budget.

package/selected-skills/financeskills/skills/treasury-management/references/fx-hedging.md

@@ -0,0 +1,27 @@
+# FX Hedging for Treasury
+
+## Exposure Taxonomy
+- **Transaction**: booked receivables/payables in foreign currency — hedge mechanically.
+- **Forecast**: probable future revenues/costs — hedge a declining ratio (e.g., 80% next quarter, 50% out 12 months).
+- **Translation**: net investment in foreign subsidiaries — usually NOT hedged with cash instruments unless covenant/ratio-driven.
+- **Economic/competitive**: pricing-power erosion — managed structurally (sourcing, pricing), not with derivatives.
+
+## Instrument Selection
+| Instrument | Use | Cost Profile |
+|---|---|---|
+| Forward/NDF | Firm exposures, illiquid currencies (NDF for NGN, partial convertibility) | Zero premium; locks rate (forward points = carry) |
+| Vanilla option | Uncertain exposures (bids, forecasts) | Premium; keeps upside |
+| Collar | Premium reduction | Caps both directions |
+| Cross-currency swap | Debt in foreign currency | Converts principal + coupons |
+| Natural hedge | Match currency of revenue and cost/debt | Free — exhaust first |
+
+## High-Carry Currency Reality (NGN and peers)
+Forward points on high-interest-differential currencies make systematic forward hedging expensive (you pay the carry). Alternatives: increase natural hedging, hold hard-currency buffers, hedge selectively around known events, use options when implied vol is cheap relative to realized.
+
+## Hedge Accounting (IFRS 9)
+- Cash flow hedge: effective portion → OCI, recycle when hedged item hits P&L. Documentation at inception: risk, instrument, hedged item, effectiveness method (1:1 critical terms or regression).
+- Forward points/option time value: may be treated as cost of hedging (OCI amortization) — reduces P&L noise.
+- Without hedge accounting, MTM volatility lands in P&L — decide deliberately.
+
+## Policy Skeleton
+Hedge ratios by horizon, approved instruments (no written naked options), counterparty limits by rating, mandatory competitive quotes (≥ 2), monthly effectiveness and exposure reporting to treasury committee.

package/selected-skills/financeskills/skills/treasury-management/references/liquidity-metrics.md

@@ -0,0 +1,24 @@
+# Liquidity Metrics and Cash Management
+
+## Core Metrics
+- **Daily cash position** = Σ available balances (by currency, by bank) + committed undrawn facilities − same-day obligations.
+- **Cash conversion cycle (CCC)** = DSO + DIO − DPO. Shorter = less funding needed. Track quarterly by business unit.
+  - DSO = AR / Revenue × days; DIO = Inventory / COGS × days; DPO = AP / COGS × days.
+- **Minimum liquidity threshold**: ≥ (1 month opex + debt service + a stress buffer); board-approved, never breached silently.
+- **Liquidity headroom** = unrestricted cash + undrawn committed facilities − minimum threshold.
+
+## Forecasting Discipline
+- **13-week rolling forecast** (weekly buckets): receipts from AR aging × collection curve; disbursements from AP, payroll calendar, tax calendar, debt service, capex schedule.
+- Direct method for 13 weeks; indirect (P&L-derived) for 12 months.
+- Variance discipline: weekly actual-vs-forecast, investigate > 10% line variances; rolling re-forecast every week, not month.
+
+## Concentration & Structure
+- Cash pooling: physical sweep vs. notional; watch intercompany loan creation (transfer pricing + thin cap + CBN approvals for cross-border).
+- Counterparty limits: max % of cash per bank, by rating tier; government securities ladder for excess.
+- Trapped cash map: balances by jurisdiction with repatriation constraints (FX controls, dividend capacity) — Nigeria: CBN documentation requirements make this a real planning item.
+
+## Stress Testing
+Run quarterly: top customer non-payment (30/60/90-day), 20% FX devaluation, revolver unavailable, 1-month revenue stop. Headroom must survive the combined moderate scenario; document management actions per trigger.
+
+## Early-Warning Indicators
+DSO creep > 5 days vs. trailing year; payee-initiated payment-term renegotiations; utilization of revolver for payroll (red line); supplier prepayment demands.

package/selected-skills/financeskills/skills/variance-analysis/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - variance-analysis
+
+## Ask
+
+> We expected to use 1,000 lbs of steel at $5/lb. We actually used 1,100 lbs at $4.50/lb. Calculate the variances.
+
+## What a correct response contains
+
+Should calculate Material Price Variance ($0.50 favorable * 1,100 lbs = $550 F). Should calculate Material Usage Variance (100 lbs unfavorable * $5 = $500 U). Should provide a Production Variance Report.
+
+## File-driven variant
+
+With fixture(s) `evals/files/production_data.xlsx`:
+
+> Compute material price, material usage, labor rate, and labor efficiency variances from the attached production workbook (evals/files/production_data.xlsx). Label each favourable/adverse and explain the most material driver.
+
+Expected: MPV -25,500 (adverse), MUV -30,000, LRV -15,620 (adverse), LEV 20,000.
+
+## 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/variance-analysis/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: variance-analysis
+description: When the user wants to analyze the difference between actual and standard costs in manufacturing. Also use when the user mentions "material price variance," "labor efficiency," "overhead variance," "standard costing," or "production audit."
+metadata:
+  version: 1.0.0
+---
+
+# Standard Cost Variance Analysis
+
+You are a Plant Controller. Your goal is to identify exactly *why* actual production costs differed from the budget—whether due to price, volume, or efficiency.
+
+## Initial Assessment
+
+1. **Standard Inputs**
+   - Standard Price ($P_s$) and Standard Quantity ($Q_s$) per unit.
+   - Standard Labor Rate ($R_s$) and Standard Hours ($H_s$) per unit.
+
+2. **Actual Results**
+   - Actual Price ($P_a$) and Actual Quantity used ($Q_a$).
+   - Actual Labor Rate ($R_a$) and Actual Hours worked ($H_a$).
+
+---
+
+## Variance Framework
+
+### Material Variances
+1. **Price Variance**: `(Standard Price - Actual Price) * Actual Quantity`.
+2. **Usage Variance**: `(Standard Quantity - Actual Quantity) * Standard Price`.
+
+### Labor Variances
+1. **Rate Variance**: `(Standard Rate - Actual Rate) * Actual Hours`.
+2. **Efficiency Variance**: `(Standard Hours - Actual Hours) * Standard Rate`.
+
+---
+
+## Technical Analysis Steps
+
+### 1. Root Cause Identification
+- Was the **Price Variance** due to a bad purchasing deal or a market spike?
+- Was the **Efficiency Variance** due to machine downtime or poor training?
+
+### 2. Overhead Variance
+- Fixed Overhead Spending Variance.
+- Fixed Overhead Volume Variance (Over/Under absorption).
+
+---
+
+## Output Format
+
+### Production Variance Report
+
+**Summary Dashboard**
+- **Total Variance**: $X (Favorable/Unfavorable).
+- **Primary Driver**: (e.g., "70% of variance driven by material price").
+
+**Variance Table**
+- Material Price | Material Usage | Labor Rate | Labor Efficiency | Overhead.
+
+**Corrective Actions**
+- Recommended fixes for unfavorable variances (e.g., "Retrain shift B," "Search for new copper supplier").
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Material, labor, and overhead variance functions. Run with `python3 scripts/calculate.py` to self-test; import the functions for actual computations.
+
+---
+
+## References
+- [Variance Formulas](./references/variance-math.md): Quick look-up for all manufacturing variances.
+- [Absorption vs. Variable Costing](./references/overhead-logic.md): Understanding fixed overhead.
+
+---
+
+## Related Skills
+- **product-profitability**: To see how variances impact SKU-level margins.
+- **budget-forecast**: For setting the "Standard Costs" for the next period.
+- **audit-checklist**: For auditing the accuracy of production reporting.

package/selected-skills/financeskills/skills/variance-analysis/references/overhead-logic.md

@@ -0,0 +1,24 @@
+# Overhead Variance Logic: Absorption vs. Variable Costing
+
+## The Four-Way Overhead Variance Split
+**Variable overhead:**
+- Spending: `(Actual VOH rate − Standard rate) × Actual hours` — price of the overhead inputs.
+- Efficiency: `(Actual hours − Standard hours allowed) × Standard VOH rate` — driven by the same hours as labor efficiency.
+
+**Fixed overhead:**
+- Spending (budget): `Actual FOH − Budgeted FOH` — the only "real" fixed overhead control variance.
+- Volume: `Budgeted FOH − Applied FOH` where `Applied = Standard hours allowed × FOH rate` — an ARTIFACT of unitizing fixed costs, not a cost control signal. Unfavorable volume variance = produced below denominator level.
+
+## Denominator Choice Matters
+FOH rate = Budgeted FOH / denominator activity. Choosing theoretical vs. practical vs. normal vs. budgeted capacity changes the rate and the volume variance. Practical capacity (recommended, and required for some costing under ASC 330/IAS 2 logic) exposes the cost of idle capacity rather than burying it in product cost.
+
+## Absorption vs. Variable Costing P&L Effect
+- `Absorption income − Variable income = ΔInventory units × FOH rate`
+- Production > sales → absorption income HIGHER (fixed cost parked in inventory). This creates the classic overproduction incentive — producing for the warehouse to flatter margins. Watch for it in bonus-driven plants.
+- IAS 2 / GAAP external reporting REQUIRES absorption; use variable costing internally for CVP and control.
+
+## Under/Over-Applied Overhead Disposal
+Immaterial → close to COGS. Material → prorate across WIP, FG, COGS based on applied overhead in each. Abnormal idle capacity cost → expense immediately, never inventory.
+
+## Interpretation Discipline
+Volume variance tells you about CAPACITY UTILIZATION, spending variance about COST CONTROL. Reporting them as one number invites the wrong fix.

package/selected-skills/financeskills/skills/variance-analysis/references/variance-math.md

@@ -0,0 +1,35 @@
+# Manufacturing Variance Formulas
+
+Quick-reference for calculating standard costing variances in a production environment.
+
+## 🏛️ Material Variances
+
+### Material Price Variance (MPV)
+`MPV = (Standard Price - Actual Price) * Actual Quantity`
+- **Favorable**: If Actual Price < Standard Price.
+
+### Material Usage Variance (MUV)
+`MUV = (Standard Quantity - Actual Quantity) * Standard Price`
+- **Favorable**: If Actual Quantity < Standard Quantity.
+
+---
+
+## 🏛️ Labor Variances
+
+### Labor Rate Variance (LRV)
+`LRV = (Standard Rate - Actual Rate) * Actual Hours`
+- **Favorable**: If Actual Rate < Standard Rate.
+
+### Labor Efficiency Variance (LEV)
+`LEV = (Standard Hours - Actual Hours) * Standard Rate`
+- **Favorable**: If Actual Hours < Standard Hours.
+
+---
+
+## 🔍 Overhead Variances
+- **Variable Overhead Spending**: `(Standard Rate - Actual Rate) * Actual Hours`.
+- **Variable Overhead Efficiency**: `(Standard Hours - Actual Hours) * Standard Rate`.
+
+## 🔗 Sources
+- [CFI: Variance Analysis](https://corporatefinanceinstitute.com/resources/accounting/variance-analysis/)
+- [AccountingCoach: Standard Costing](https://www.accountingcoach.com/standard-costing/explanation)

package/selected-skills/financeskills/skills/venture-debt/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - venture-debt
+
+## Ask
+
+> We're a Series B startup with $5M in MRR. We want to borrow $10M in venture debt to avoid dilution. What should we expect for terms?
+
+## What a correct response contains
+
+Should identify that venture debt is typically 20-30% of the last equity round or linked to MRR multiples. Should discuss Warrants and Covenants (Minimum Cash/MRR). Should provide a Venture Debt Term Sheet structure.
+
+## File-driven variant
+
+With fixture(s) `evals/files/term_sheet.csv`:
+
+> Analyze the attached venture-debt term sheet (evals/files/term_sheet.csv): build the 36-month payment schedule (12 IO + 24 amortizing), total cost of debt including fees, warrant shares, and runway extension from net proceeds.
+
+Expected: Total interest+fees $1,498,817; warrants 200,000 shares; runway extension 7.1 months; monthly payment in amortization ~$235,367.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) - import its functions rather than doing arithmetic in prose.