@v587d/capital-generation 2.7.6 → 2.7.8

package/selected-skills/financeskills/skills/oil-gas-valuation/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - oil-gas-valuation
+
+## Ask
+
+> We have 1 million barrels of proved reserves. Lifting costs are $15/bbl. Current oil price is $80/bbl. What's the PV-10 assuming a 10-year production life?
+
+## What a correct response contains
+
+Should calculate annual production (100k bbl/yr). Should calculate annual net cash flow ($80 - $15 = $65/bbl * 100k = $6.5M/yr). Should discount the 10-year annuity at 10% to find PV-10 (approx. $39.9M). Should provide an Oil & Gas Valuation Memo.
+
+## File-driven variant
+
+With fixture(s) `evals/files/field_parameters.csv`:
+
+> Value the field described in the attached parameters (evals/files/field_parameters.csv): build the 10-year exponential decline profile, compute the per-barrel netback, and the PV-10.
+
+Expected: Netback $41.50/bbl; year-10 production 387,420 bbl; PV-10 $179,605,644.
+
+## 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/oil-gas-valuation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: oil-gas-valuation
+description: When the user wants to value oil and gas reserves or perform upstream financial analysis. Also use when the user mentions "PV-10," "proven reserves (1P)," "probable reserves (2P)," "lifting costs," "decline curve analysis," or "upstream valuation."
+metadata:
+  version: 1.0.0
+---
+
+# Oil & Gas Reserve Valuation
+
+You are an Upstream Energy Analyst. Your goal is to estimate the economic value of sub-surface hydrocarbons based on geological certainty and current market pricing.
+
+## Initial Assessment
+
+1. **Reserve Categorization**
+   - **Proved (1P)**: 90% probability of recovery.
+   - **Probable (2P)**: 50% probability of recovery.
+   - **Possible (3P)**: 10% probability of recovery.
+
+2. **Cost Structure**
+   - **Lifting Costs**: Direct costs to bring oil to the surface.
+   - **Finding & Development (F&D) Costs**: Costs to discover and build infrastructure.
+
+3. **Pricing Assumptions**
+   - Standardized pricing (e.g., SEC 12-month average) or forward curve?
+
+---
+
+## Valuation Framework
+
+### The PV-10 Calculation
+`PV-10 = Σ [Net Cash Flow_t / (1.10)^t]`
+- Net Cash Flow = Revenue - Production Taxes - Lifting Costs - Development CapEx.
+- Note: PV-10 is pre-tax; Standardized Measure (SM) is post-tax.
+
+### Priority Order
+1. **Production Forecasting** (Using decline curves).
+2. **Revenue Modeling** (Price x Production).
+3. **OpEx & CapEx Deduction** (Calculating net cash flow).
+4. **Discounting** (Applying the standard 10% rate).
+5. **Reserve Life Calculation** (Reserves / Annual Production).
+
+---
+
+## Technical Analysis Steps
+
+### 1. Decline Curve Analysis (DCA)
+- Model the natural drop in production over time (Exponential, Hyperbolic, or Harmonic).
+
+### 2. SEC Standardized Measure
+- Apply the mandatory SEC rules for reporting reserve value in financial statements (10-K).
+
+---
+
+## Output Format
+
+### Oil & Gas Valuation Memo
+
+**Reserve Summary**
+- 1P, 2P, and 3P quantities in BOE (Barrels of Oil Equivalent).
+- Reserve Life Index (RLI).
+
+**Financial Metrics**
+- **PV-10 Value**: $X.
+- **Lifting Cost per BOE**: $Y.
+- **F&D Cost per BOE**: $Z.
+
+**Sensitivity**
+- Table showing PV-10 sensitivity to +/- $10 change in oil price.
+
+---
+
+## 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
+- [SPE Reserve Definitions](./references/spe-standards.md): Industry definitions for 1P/2P/3P.
+- [PV-10 vs. Standardized Measure](./references/sec-reporting.md): Difference between pre-tax and post-tax valuation.
+
+---
+
+## Related Skills
+- **aro-computation**: For the decommissioning of wells and platforms.
+- **investment-analysis**: For valuing integrated oil companies.
+- **financial-analysis**: For analyzing the cash flow of E&P firms.

package/selected-skills/financeskills/skills/oil-gas-valuation/references/sec-reporting.md

@@ -0,0 +1,22 @@
+# SEC Oil & Gas Reporting Requirements
+
+## Reserve Categories (SEC Modernized Rules, Reg S-X 4-10)
+- **Proved (1P)**: reasonable certainty (≥ 90% for probabilistic); economically producible under EXISTING economic conditions. Subcategories: PDP (developed producing), PDNP (developed non-producing), PUD (undeveloped).
+- **PUD 5-year rule**: undeveloped locations must have a development plan with drilling scheduled within 5 years of initial booking, or de-book.
+- Probable (2P incremental, ≥ 50%) and possible (3P incremental, ≥ 10%) MAY be disclosed but not required.
+
+## SEC Pricing Convention
+12-month average of first-day-of-month benchmark prices, held FLAT for the life of reserves (no escalation), adjusted for quality/transport differentials. This is the defining difference from bank/NPV decks which use forward strips.
+
+## Standardized Measure (ASC 932)
+PV of future net revenues from proved reserves: SEC prices × production schedule − development costs − production costs − income taxes, all discounted at a MANDATED 10% — the "standardized measure." **PV-10** is the non-GAAP pre-tax cousin (reconcile when disclosed).
+
+## Required Disclosures (annual)
+- Reserve quantities rollforward by product and geography: revisions, extensions/discoveries, improved recovery, purchases/sales, production.
+- Capitalized costs, costs incurred (acquisition/exploration/development), results of operations for O&G activities.
+- Standardized measure rollforward.
+- Third-party reserve engineer involvement and internal qualified person credentials.
+
+## Accounting Method Interplay
+- Successful efforts vs. full cost: ceiling test (full cost) uses the SEC price deck — price collapses trigger mechanical impairments.
+- Nigeria note: NUPRC reserve reporting and local content rules sit alongside; reconcile SEC-basis vs. PRMS-basis (SPE) bookings — the categories do NOT map one-to-one (see spe-standards.md).

package/selected-skills/financeskills/skills/oil-gas-valuation/references/spe-standards.md

@@ -0,0 +1,25 @@
+# SPE Petroleum Resources Management System (PRMS)
+
+The industry-standard framework for classifying and estimating petroleum resources.
+
+## 🏛️ Classification Categories
+
+### 1. Proved Reserves (1P)
+- **P90**: There is at least a 90% probability that the quantities actually recovered will equal or exceed the estimate.
+- **Criteria**: Based on geological and engineering data; must be economically producible under existing economic conditions.
+
+### 2. Probable Reserves (2P)
+- **P50**: The sum of Proved and Probable reserves where there is at least a 50% probability that the quantities actually recovered will equal or exceed the estimate.
+
+### 3. Possible Reserves (3P)
+- **P10**: The sum of Proved, Probable, and Possible reserves where there is at least a 10% probability that the quantities actually recovered will equal or exceed the estimate.
+
+---
+
+## 🔍 Key Definitions
+- **BOE (Barrel of Oil Equivalent)**: Used to combine oil and gas into a single measure based on energy content (typically 6 Mcf of gas = 1 Bbl of oil).
+- **RLI (Reserve Life Index)**: Total Reserves / Annual Production.
+
+## 🔗 Sources
+- [SPE Official PRMS Guide](https://www.spe.org/en/industry/reserves/)
+- [WPC: Petroleum Resources Management System](https://www.world-petroleum.org/)

package/selected-skills/financeskills/skills/personal-budgeting/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - personal-budgeting
+
+## Ask
+
+> My take-home is $4,500/month. I spend roughly $1,800 on rent, $600 on food, $300 on transport, $200 utilities, $400 subscriptions/dining/fun, and $200 on gym and hobbies. I never seem to save anything. Help me build a budget.
+
+## What a correct response contains
+
+Should calculate total expenses ($3,500) and surplus ($1,000). Should apply the 50/30/20 rule: Needs target $2,250, Wants target $1,350, Savings target $900. Should identify that Needs ($2,900) exceed the 50% target. Should recommend moving the savings surplus to an automated transfer. Should provide a concrete action plan with category-level reductions.
+
+## File-driven variant
+
+With fixture `evals/files/monthly_expenses.csv`:
+
+> From the attached monthly expense data (evals/files/monthly_expenses.csv), calculate my savings rate, compare actual spending to the 50/30/20 targets, and tell me the top category to cut to reach a 20% savings rate.
+
+Expected: income $5,000; Needs $2,600 (52%), Wants $1,300 (26%), Savings $600 (12%); savings rate 12%; needs to save $1,000/month for 20% target; top cut category is Dining ($400).
+
+## 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/personal-budgeting/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: personal-budgeting
+description: When the user wants to create a personal budget, track income vs. expenses, apply the 50/30/20 rule, build a zero-based budget, improve their savings rate, or understand where their money is going. Also use when the user mentions "I'm overspending," "I can't save money," "monthly budget," "budget categories," or "living paycheck to paycheck."
+metadata:
+  version: 1.0.0
+---
+
+# Personal Budgeting
+
+You are a Personal Finance Coach. Your goal is to help the user build a clear, realistic spending plan so that every dollar has a purpose and savings become non-negotiable.
+
+## Initial Assessment
+
+1. **Income Picture**
+   - What is the user's monthly take-home (after-tax) income?
+   - Are income streams fixed (salary) or variable (freelance, commission)?
+
+2. **Spending Baseline**
+   - Do they have 1–3 months of bank/card statements to analyze?
+   - Are any expenses irregular (annual subscriptions, seasonal costs)?
+
+3. **Goal Clarity**
+   - What is the primary financial goal? (Emergency fund, debt payoff, vacation, house deposit.)
+   - What is the target savings rate?
+
+---
+
+## Budgeting Framework
+
+### Priority Order
+1. **Income Capture** — confirmed monthly take-home.
+2. **Fixed Essentials First** — rent/mortgage, utilities, insurance, minimum debt payments.
+3. **Variable Essentials** — groceries, transport, medical.
+4. **Discretionary Wants** — dining out, subscriptions, entertainment.
+5. **Savings & Investments** — treat as a fixed expense, not a leftover.
+
+### Two Approaches
+
+**50/30/20 Rule** (simple starting point)
+- 50% Needs (housing, utilities, food, transport, minimum debt payments)
+- 30% Wants (dining, subscriptions, hobbies, travel)
+- 20% Savings & debt repayment above minimums
+
+**Zero-Based Budget** (maximum control)
+- Allocate every dollar of income to a named category until Income − Expenses = 0.
+- Review and reallocate monthly.
+
+---
+
+## Technical Steps
+
+### 1. Categorise All Spending
+Group every transaction into Needs, Wants, or Savings for the past 90 days.
+
+### 2. Calculate Savings Rate
+`Savings Rate = (Monthly Savings / Monthly Income) × 100`
+
+A savings rate below 10% is a warning sign. Target ≥ 20% for long-term wealth building.
+
+### 3. Identify Gaps
+- Where does spending exceed the 50/30/20 targets?
+- Which discretionary categories have the biggest reduction opportunity?
+
+### 4. Build the Plan
+- Set category caps for the coming month.
+- Automate savings transfers on payday ("pay yourself first").
+
+---
+
+## Output Format
+
+**Budget Summary**
+- Monthly income and categorised totals (Needs / Wants / Savings).
+- Actual vs. 50/30/20 target comparison.
+- Surplus or deficit.
+
+**Action Plan**
+- Top 3 spending categories to reduce with specific targets.
+- Recommended savings automation schedule.
+
+**30-Day Check-in Template**
+- Simple tracking table to compare plan vs. actual.
+
+---
+
+## 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
+- [Budgeting Methods](./references/budgeting-methods.md): Comparison of 50/30/20, zero-based, envelope, and pay-yourself-first methods.
+- [Spending Categories Guide](./references/spending-categories.md): Standard category taxonomy for personal budgets.
+
+---
+
+## Related Skills
+- **debt-payoff**: Once a budget surplus is identified, apply it to a structured debt elimination plan.
+- **net-worth-tracker**: Use the budget as the input to a monthly net worth update.
+- **retirement-planning**: Translate the savings line in the budget into a long-term retirement projection.

package/selected-skills/financeskills/skills/personal-budgeting/references/budgeting-methods.md

@@ -0,0 +1,40 @@
+# Budgeting Methods
+
+A comparison of the four most widely used personal budgeting frameworks.
+
+## 1. 50/30/20 Rule
+Popularised by Senator Elizabeth Warren in *All Your Worth* (2005).
+- **50% Needs**: rent, utilities, groceries, transport, minimum debt payments.
+- **30% Wants**: dining, entertainment, subscriptions, hobbies.
+- **20% Savings & extra debt repayment**.
+
+Best for: beginners who want a simple, low-maintenance system.
+
+## 2. Zero-Based Budget
+Every dollar of income is assigned a category until Income − Expenses = $0.
+- Forces intentional spending decisions.
+- Requires monthly rebuilding of the budget.
+
+Best for: people with irregular spending or those aggressively paying off debt.
+
+## 3. Envelope Method
+Cash is divided into physical (or digital) envelopes per category. When the envelope is empty, spending stops.
+- Eliminates overspending in variable categories.
+- Works well paired with zero-based budgeting.
+
+Best for: people who overspend on discretionary categories.
+
+## 4. Pay-Yourself-First
+Savings are automated on payday before any other spending occurs. The remainder is spent freely.
+- Savings target is guaranteed regardless of discipline.
+- Does not control spending, only ensures savings.
+
+Best for: high earners who save enough but want more structure.
+
+## Recommended Starting Point
+Begin with the 50/30/20 rule to establish a baseline. Transition to zero-based budgeting once the baseline reveals problem areas.
+
+## Sources
+- Warren, E. & Warren Tyagi, A. (2005). *All Your Worth*. Free Press.
+- [NerdWallet: 50/30/20 Budget Rule](https://www.nerdwallet.com/article/finance/nerdwallet-budget-calculator)
+- [YNAB: Zero-Based Budgeting](https://www.ynab.com/zero-based-budgeting)

package/selected-skills/financeskills/skills/personal-budgeting/references/spending-categories.md

@@ -0,0 +1,40 @@
+# Spending Categories Guide
+
+Standard taxonomy for classifying personal expenses. Use consistently across months for valid trend analysis.
+
+## Needs (Essential)
+| Category | Examples |
+|---|---|
+| Housing | Rent, mortgage, property tax, HOA |
+| Utilities | Electricity, gas, water, internet, phone |
+| Groceries | Supermarket food and household basics |
+| Transport | Fuel, public transit, car insurance, maintenance |
+| Insurance | Health, life, renters/home |
+| Minimum debt payments | Credit card minimums, student loan minimums |
+| Childcare / education | School fees, daycare |
+
+## Wants (Discretionary)
+| Category | Examples |
+|---|---|
+| Dining & takeaway | Restaurants, cafes, food delivery |
+| Entertainment | Streaming, cinema, concerts, sports |
+| Subscriptions | Software, magazines, gym (if non-essential) |
+| Clothing | Non-essential apparel and accessories |
+| Hobbies | Sports equipment, crafts, gaming |
+| Travel | Holidays, weekend trips |
+| Personal care | Haircuts, cosmetics above basics |
+
+## Savings & Debt Payoff
+| Category | Examples |
+|---|---|
+| Emergency fund | High-yield savings account contributions |
+| Retirement | 401(k), IRA, pension contributions |
+| Investments | Brokerage, ISA, index funds |
+| Extra debt repayment | Above-minimum payments on loans/cards |
+| Sinking funds | Car replacement, home repairs, annual expenses |
+
+## Classification Tips
+- **Internet**: Needs if required for work/study; Wants if purely recreational.
+- **Gym membership**: Needs if medically required; Wants otherwise.
+- **Life insurance**: Always a Need.
+- **Streaming services**: Wants (one service could be debated as Need if it replaces more expensive entertainment).

package/selected-skills/financeskills/skills/predictive-burn-rate/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - predictive-burn-rate
+
+## Ask
+
+> Our burn rate has been $100k, $120k, and $150k over the last 3 months. We have $1M in the bank. When do we run out of money?
+
+## What a correct response contains
+
+Should identify the accelerating burn trend. Should note that a simple average is dangerous due to the acceleration. Should calculate the 'Zero Date' based on the trend (approx. 5-6 months). Should suggest using Prophet for a more detailed seasonal forecast. Should provide a Runway Forecast Report.
+
+## File-driven variant
+
+With fixture(s) `evals/files/monthly_cash.csv`:
+
+> Cash on hand is $7,500,000. Using the attached six months of actuals (evals/files/monthly_cash.csv), compute monthly net burn, the trailing 3-month average, simple runway in months, and comment on the burn trend.
+
+Expected: Net burn rising from $510,000 to $584,000; trailing 3-month avg $569,667; simple runway 13.2 months; trend-adjusted runway is shorter - flag it.
+
+## 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/predictive-burn-rate/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: predictive-burn-rate
+description: When the user wants to predict future cash consumption and "Runway" using time-series AI models. Also use when the user mentions "startup runway," "predicting cash out," "future burn rate," "Prophet for finance," "LSTM cash forecasting," or "when will we run out of money."
+metadata:
+  version: 1.0.0
+---
+
+# Predictive Burn Rate
+
+You are a Startup Data Scientist. Your goal is to use time-series forecasting to predict exactly when a company will require more capital, accounting for seasonality and growth trends.
+
+## Initial Assessment
+
+1. **Cash Flow Data**
+   - Do we have monthly net cash flow (Net Burn) for at least 12-24 months?
+   - What are the major "lumpy" expenses? (e.g., Annual software renewals, bi-annual bonuses).
+
+2. **Growth Assumptions**
+   - Are headcount and marketing spend scaling linearly or exponentially?
+   - Is there a "Target Zero" date for profitability?
+
+---
+
+## Predictive Framework
+
+### Technical Limitation
+Linear extrapolations (Actuals / Average Burn) are often wrong because they ignore seasonality. This skill uses **Prophet** or **ARIMA** logic for more accurate modeling.
+
+### Priority Order
+1. **Decomposition** (Separating Trend, Seasonality, and Noise).
+2. **Growth Modeling** (Adjusting the burn rate based on headcount growth).
+3. **Runway Calculation** (Predicting the month the cash balance hits zero).
+4. **Buffer Analysis** (Identifying the "Safety Zone" for fundraising).
+
+---
+
+## Technical Predictive Steps
+
+### 1. Time-Series Decomposition
+- Identify if the burn rate is increasing due to a long-term trend or a one-time seasonal spike (e.g., Q4 marketing push).
+
+### 2. Facebook Prophet Integration
+- Use the `Prophet` library to handle missing data and outliers while modeling complex seasonality (holiday effects).
+
+### 3. Scenario Probability
+- Instead of one date, provide a probability distribution: "70% chance of cash out in Oct, 20% in Nov, 10% in Dec."
+
+---
+
+## Output Format
+
+### Runway Forecast Report
+
+**The Prediction**
+- **Estimated Cash Out Date**: The "Zero Date."
+- **Current Runway**: Expressed in months.
+- **Trend Rating**: (e.g., "Accelerating Burn," "Stabilizing").
+
+**AI Visuals (Description)**
+- Confidence intervals for the next 12 months.
+- Breakdown of burn drivers (fixed vs. variable).
+
+**Actionable Insight**
+- "Fundraising Trigger": The date you must start your next round to avoid a cash crunch.
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Runway, growth-adjusted burn, and collections curve functions. Run with `python3 scripts/calculate.py` to self-test; import the functions for actual computations.
+
+---
+
+## References
+- [Time Series Basics](./references/time-series-forecasting.md): ARIMA vs. Prophet.
+- [Startup Runway Metrics](./references/startup-metrics.md): How VCs look at burn.
+
+---
+
+## Related Skills
+- **budget-forecast**: For the manual planning of the burn rate.
+- **treasury-management**: For managing the cash reserves predicted here.
+- **investment-analysis**: For valuing the startup based on its burn and growth.

package/selected-skills/financeskills/skills/predictive-burn-rate/references/startup-metrics.md

@@ -0,0 +1,27 @@
+# Startup Financial Metrics
+
+## Burn and Runway
+- **Gross burn**: total monthly cash outflows.
+- **Net burn**: gross burn − cash collections. The runway number.
+- **Runway**: months until cash < safety floor. Investors expect 18–24 months post-raise.
+- **Default alive test** (Paul Graham): at current growth and burn trajectory, does the company reach profitability before cash-out?
+
+## Efficiency Metrics
+- **Burn multiple** = Net burn / Net new ARR. < 1 excellent, 1–1.5 good, > 2 concerning (Sacks framework).
+- **CAC payback** = CAC / (new ARR per customer × gross margin), in months. < 12 strong, < 18 acceptable B2B.
+- **LTV:CAC** ≥ 3 healthy (but meaningless pre-churn-data).
+- **Magic number** = Net new ARR × 4 / prior-quarter S&M spend. > 0.75 → keep investing in sales.
+- **Rule of 40**: revenue growth % + FCF margin % ≥ 40 (later stage).
+
+## Revenue Quality
+- **NRR (net revenue retention)**: > 110% B2B good, > 120% excellent.
+- **Gross margin**: SaaS benchmark 70–85%; services-heavy mix drags it.
+- **ARR vs. recognized revenue vs. billings**: never conflate (see SaaS rev rec).
+
+## Fundraise Planning Inputs
+- Months-to-milestone vs. runway: raise must cover milestone + 6-month buffer.
+- Dilution math: target 15–25% per priced round.
+- Bridge triggers: < 9 months runway without a started process = act now.
+
+## Reporting Cadence
+Monthly investor update: cash, net burn, runway, ARR, NRR, headcount vs. plan — consistency beats polish.

package/selected-skills/financeskills/skills/predictive-burn-rate/references/time-series-forecasting.md

@@ -0,0 +1,22 @@
+# Time-Series Forecasting for Cash Burn
+
+## Method Ladder (use the simplest that fits)
+1. **Trailing average**: 3-month average net burn — baseline every model must beat.
+2. **Linear trend / Holt's exponential smoothing**: captures burn growth; Holt-Winters if seasonality (annual insurance, 13th-month payroll).
+3. **Driver-based decomposition** (preferred for runway): forecast components separately —
+   `Net burn = Payroll (headcount plan × loaded cost) + Contracted opex (schedule) + Variable opex (% of activity) − Collections (bookings × collection curve)`
+4. **ARIMA/SARIMA**: only with ≥ 24 months of clean history; rarely better than driver-based for startups.
+5. **Monte Carlo**: simulate collections timing, hiring slippage, FX; report runway as a distribution (P10/P50/P90), not a point.
+
+## Collections Curve
+Model receipts as a lagged distribution of invoicing: e.g., 20% month 0, 50% month 1, 25% month 2, 5% bad debt — fit from AR aging history. The curve, not revenue, drives cash.
+
+## Runway Mathematics
+- Simple: `Runway = Cash / trailing 3-mo net burn`.
+- Honest: project monthly cash to the month balance < safety floor (≥ 1 payroll cycle + statutory obligations), including known one-offs (tax payments, annual renewals, severance).
+- Growing burn: if burn grows g monthly, runway solves `Cash = Σ burn×(1+g)^t` — materially shorter than the simple division.
+
+## Discipline
+- Reforecast monthly; track forecast-vs-actual error (MAPE ≤ 10% is good for 3-month horizon).
+- Separate committed vs. discretionary spend so scenario levers are real.
+- Never net financing inflows into operating burn — report both.

package/selected-skills/financeskills/skills/product-profitability/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - product-profitability
+
+## Ask
+
+> Our 'Premium' service has 80% gross margins but only 5% of our sales. Our 'Standard' service has 20% margins but 95% of sales. Should we shut down 'Standard'?
+
+## What a correct response contains
+
+Should perform a Contribution Margin analysis. Should warn against shutting down 'Standard' if it covers the majority of fixed overhead. Should discuss the impact of fixed cost re-allocation. Should provide a Product Profitability Dashboard.
+
+## File-driven variant
+
+With fixture(s) `evals/files/product_lines.csv`:
+
+> Build a product P&L from the attached file (evals/files/product_lines.csv): allocate the $900,000 shared cost pool by revenue, compute contribution margin and fully-loaded profit per product, and identify any product that is contribution-positive but fully-loaded negative.
+
+Expected: Alpha profit $1,860,000; Beta $630,000; Gamma $60,000 - Gamma is contribution-positive ($150,000) but fully-loaded negative.
+
+## 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/product-profitability/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: product-profitability
+description: When the user wants to break down revenue and costs by specific products, services, or segments. Also use when the user mentions "unit economics," "product-line P&L," "contribution margin," "SKU profitability," "segment reporting," or "cost allocation."
+metadata:
+  version: 1.0.0
+---
+
+# Product & Service Profitability Analysis
+
+You are a Management Accountant. Your goal is to identify which products or services are driving the most value and which are eroding margins.
+
+## Initial Assessment
+
+1. **Segment Definition**
+   - Are we analyzing by SKU, Product Category, or Service Line?
+   - What is the time period?
+
+2. **Data Availability**
+   - Can we track revenue directly to the segment?
+   - Can we track variable costs (COGS) directly?
+   - What is the total pool of indirect/fixed costs?
+
+---
+
+## Profitability Framework
+
+### Priority Order
+1. **Direct Revenue Attribution** (Matching sales to products).
+2. **Variable Cost Assignment** (Calculating the Contribution Margin).
+3. **Fixed Cost Allocation** (Determining the "Fully Burdened" margin).
+4. **Variance Analysis** (Comparing actual product performance to budget).
+5. **Strategic Recommendations** (e.g., "Kill product X," "Scale product Y").
+
+---
+
+## Technical Analysis Steps
+
+### 1. Contribution Margin Analysis
+`CM = Revenue - Variable Costs`
+- This shows how much each product contributes to covering fixed overhead.
+
+### 2. Allocation Methodologies
+- **Direct**: Costs mapped 1:1.
+- **Activity-Based (ABC)**: Costs allocated based on drivers (e.g., machine hours, customer service tickets).
+- **Step-Down**: Allocating support department costs to production departments.
+
+### 3. Mix Variance
+- Analyze if a shift in the *proportion* of products sold (Product Mix) is impacting the overall gross margin.
+
+---
+
+## Output Format
+
+### Product Profitability Dashboard
+
+**The Stack Rank**
+- Table of products ranked by Gross Margin and Contribution Margin %.
+
+**Segment P&L**
+- Columns for each product line showing Revenue, COGS, Direct OpEx, and Net Contribution.
+
+**Optimization Plan**
+- Identified "Laggards" (low margin/low volume).
+- Identified "Stars" (high margin/high volume).
+- Pricing or cost-cutting recommendations.
+
+---
+
+## 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
+- [Cost Allocation Methods](./references/allocation-logic.md): ABC vs. Traditional.
+- [Unit Economics Guide](./references/unit-economics.md): CAC, LTV, and Payback.
+
+---
+
+## Related Skills
+- **financial-analysis**: For the macro-level margin analysis.
+- **budget-forecast**: For setting product-level targets.
+- **statement-preparation**: For ensuring segment reporting matches the consolidated P&L.

package/selected-skills/financeskills/skills/product-profitability/references/allocation-logic.md

@@ -0,0 +1,28 @@
+# Cost Allocation Logic
+
+## Allocation Hierarchy (best to worst)
+1. **Direct tracing**: costs unambiguously caused by the product (materials, dedicated labor, product-specific licenses) — assign, don't allocate.
+2. **Causal drivers (ABC)**: allocate pooled costs on the activity that drives them.
+3. **Ability-to-bear (revenue %)**: last resort — it distorts decisions because high-revenue products subsidize the rest.
+
+## Activity-Based Costing in Five Steps
+1. Identify activities (order processing, machine setup, QA inspection, customer support, deployment).
+2. Pool costs per activity from the GL (salaries, systems, facilities split by time/space study).
+3. Pick a driver per pool: setups → # of setups; support → tickets; warehousing → pallet-days; payment processing → transaction count.
+4. Rate = pool cost / driver volume.
+5. Charge products: usage × rate.
+
+## Driver Selection Tests
+- Causality: does more of the driver actually cause more cost?
+- Measurability: is driver data captured reliably without manual heroics?
+- Materiality: pools < 5% of overhead can use a simple driver; don't gold-plate.
+
+## What NOT to Allocate for Decisions
+- Sunk costs and corporate overhead that won't change with the decision (CEO salary doesn't vanish if you kill SKU #47).
+- Use a contribution hierarchy: revenue → variable costs → **CM1** → directly attributable fixed → **CM2 (product profit)** → allocated shared costs → **CM3 (fully loaded, for pricing floors only)**.
+- Kill/keep decisions: CM2 + avoidable cost test. Pricing floors: CM3. Never reverse them.
+
+## Common Distortions
+- Volume-based allocation of batch costs (penalizes high-volume products, hides the cost of complexity).
+- Peanut-butter IT/facilities spreading on headcount when usage is wildly uneven.
+- Ignoring cost-to-serve variation by CHANNEL and CUSTOMER, not just product.