@v587d/capital-generation 2.7.7 → 2.7.8

package/selected-skills/financeskills/skills/net-worth-tracker/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - net-worth-tracker
+
+## Ask
+
+> Here are my finances: checking $3,000, savings $12,000, 401k $68,000, car value $15,000. Debts: car loan $9,000, student loan $22,000, credit card $3,500. What's my net worth and how healthy does it look?
+
+## What a correct response contains
+
+Should total assets: $98,000. Should total liabilities: $34,500. Should calculate net worth: $63,500. Should compute debt-to-asset ratio: 35% (healthy, below 50%). Should assess liquidity: liquid assets $15,000 (15% — adequate). Should flag that 401k is the dominant asset at 69% and comment on investment concentration.
+
+## File-driven variant
+
+With fixture `evals/files/balance_sheet.csv`:
+
+> From the attached balance sheet (evals/files/balance_sheet.csv), calculate net worth, debt-to-asset ratio, and asset allocation. Compare to the prior period values in the file.
+
+Expected: Current net worth $87,500; prior net worth $74,200; change +$13,300 (+17.9%); debt-to-asset ratio 28.6%; investment assets 71% of total. Primary driver of growth: retirement account appreciation.
+
+## 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/net-worth-tracker/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: net-worth-tracker
+description: When the user wants to calculate their net worth, track assets and liabilities over time, measure financial progress, analyse asset allocation, or set a net worth milestone. Also use when the user mentions "what am I worth," "assets vs debts," "balance sheet," "financial snapshot," or "am I building wealth."
+metadata:
+  version: 1.0.0
+---
+
+# Net Worth Tracker
+
+You are a Personal Financial Advisor. Your goal is to give the user a clear, honest snapshot of their total financial position and a trend they can track monthly.
+
+## Initial Assessment
+
+1. **Asset Inventory**
+   - Cash and bank accounts.
+   - Investment and retirement accounts (current market value).
+   - Real estate (current market value, not purchase price).
+   - Vehicles, business equity, other valuables.
+
+2. **Liability Inventory**
+   - Mortgage balance.
+   - Car loans, student loans, personal loans.
+   - Credit card balances.
+   - Any other debt.
+
+3. **Tracking Cadence**
+   - First-time snapshot or comparison to a previous period?
+   - Are previous-period values available?
+
+---
+
+## Calculation Framework
+
+### Net Worth Formula
+`Net Worth = Total Assets − Total Liabilities`
+
+### Asset Allocation
+Break assets into:
+- **Liquid** (cash, chequing, savings, money market) — accessible within days.
+- **Investment** (brokerage, retirement accounts) — market-value based.
+- **Illiquid** (real estate, business equity, collectibles) — estimated market value.
+
+### Key Ratios
+- **Debt-to-Asset Ratio** = Total Liabilities / Total Assets (lower is better; <0.5 is healthy).
+- **Liquid Asset Ratio** = Liquid Assets / Total Assets (target ≥ 10% for emergency resilience).
+- **Investment Asset Ratio** = Investment Assets / Total Assets (proxy for wealth-building progress).
+
+---
+
+## Technical Steps
+
+### 1. Sum All Assets by Category
+Use current market values, not book or purchase values.
+
+### 2. Sum All Liabilities
+Use outstanding balances, not original loan amounts.
+
+### 3. Calculate Net Worth and Ratios
+Compute net worth, debt-to-asset ratio, and category percentages.
+
+### 4. Period-over-Period Change
+If prior snapshot exists: compute dollar change, percentage change, and which asset/liability drove the change most.
+
+---
+
+## Output Format
+
+**Net Worth Statement**
+- Assets table (category, amount, % of total).
+- Liabilities table (category, amount, % of total).
+- Net worth and key ratios.
+
+**Trend Analysis** (if prior period available)
+- Net worth change, primary driver of change.
+
+**Health Assessment**
+- Commentary on debt-to-asset ratio, liquidity, and investment allocation.
+
+**Next Milestone**
+- Nearest round-number net worth target and months to reach it at the current savings rate.
+
+---
+
+## 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
+- [Net Worth Benchmarks](./references/net-worth-benchmarks.md): Age-based net worth benchmarks and wealth percentiles.
+- [Asset Valuation Guide](./references/asset-valuation.md): How to value illiquid assets (real estate, business equity, collectibles).
+
+---
+
+## Related Skills
+- **personal-budgeting**: The monthly savings line in the budget is the primary driver of net worth growth.
+- **debt-payoff**: Liability reduction is the fastest path to net worth improvement for debt-heavy individuals.
+- **retirement-planning**: Retirement accounts are typically the largest investment asset — ensure they are on track.

package/selected-skills/financeskills/skills/net-worth-tracker/references/asset-valuation.md

@@ -0,0 +1,40 @@
+# Asset Valuation Guide
+
+How to assign realistic values to assets for a personal balance sheet.
+
+## Liquid Assets (Easy — Use Account Balances)
+- Chequing, savings, money market: use the current account balance.
+- Cash on hand: include if material.
+
+## Investment Accounts
+- Brokerage and retirement accounts: use the current market value shown on the statement.
+- Do NOT use cost basis (what you paid) — use market value.
+
+## Real Estate
+Use current market value, not purchase price or mortgage balance.
+Estimation methods (in order of reliability):
+1. Recent appraisal (most accurate).
+2. Automated valuation models (Zillow, Redfin estimate) — reasonable proxy, ±10–15%.
+3. Comparable sales (comps) from a local real estate agent.
+
+Subtract nothing for mortgage here — that is captured on the liabilities side.
+
+## Vehicles
+- Use Kelley Blue Book or similar guide for current private-party value.
+- Depreciation is fast in the first 3 years; update annually.
+
+## Business Equity
+Difficult to value without a formal appraisal. Common shortcuts:
+- **Revenue multiple**: 0.5–1× annual revenue for service businesses.
+- **Earnings multiple**: 3–5× EBITDA for stable small businesses.
+- Use conservatively and note the uncertainty.
+
+## Collectibles & Valuables
+- Use recent auction results or certified appraisals.
+- Only include if you would realistically sell.
+- Do not include sentimental items unless they have clear market value.
+
+## What NOT to Include
+- Future earnings or bonuses (not yet received).
+- Value of pension promises (present value is complex — note separately).
+- Life insurance death benefit (only include cash surrender value if applicable).

package/selected-skills/financeskills/skills/net-worth-tracker/references/net-worth-benchmarks.md

@@ -0,0 +1,33 @@
+# Net Worth Benchmarks
+
+## The Millionaire Next Door Formula
+From Stanley & Danko (1996), a rule of thumb for expected net worth at a given age:
+
+`Expected Net Worth = Age × Annual Pre-Tax Income / 10`
+
+- **Prodigious Accumulator of Wealth (PAW)**: Net worth > 2× expected.
+- **Average Accumulator of Wealth (AAW)**: Net worth ≈ expected.
+- **Under Accumulator of Wealth (UAW)**: Net worth < 0.5× expected.
+
+## US Net Worth Percentiles by Age (Federal Reserve SCF, 2022)
+
+| Age Group | Median NW | 75th Percentile | 90th Percentile |
+|---|---|---|---|
+| Under 35 | $39,000 | $136,000 | $321,000 |
+| 35–44 | $135,000 | $404,000 | $854,000 |
+| 45–54 | $247,000 | $704,000 | $1,500,000 |
+| 55–64 | $365,000 | $1,000,000 | $2,400,000 |
+| 65–74 | $410,000 | $1,200,000 | $2,900,000 |
+
+## Healthy Ratio Targets
+
+| Ratio | Healthy Range |
+|---|---|
+| Debt-to-Asset Ratio | < 50% (ideally < 30%) |
+| Liquid Asset Ratio | ≥ 10% of total assets |
+| Investment Asset Ratio | ≥ 40% of total assets (by mid-career) |
+| Emergency Fund | 3–6 months of expenses in liquid form |
+
+## Sources
+- Stanley, T. J., & Danko, W. D. (1996). *The Millionaire Next Door*. Longstreet Press.
+- Federal Reserve Board (2022). *Survey of Consumer Finances*.

package/selected-skills/financeskills/skills/nlp-earnings-sentiment/EXAMPLE.md

@@ -0,0 +1,17 @@
+# Worked Example - nlp-earnings-sentiment
+
+## Ask
+
+> Analyze the sentiment of this earnings call transcript. Management keeps using words like 'challenging' and 'headwinds' but says the outlook is 'positive'.
+
+## What a correct response contains
+
+Should identify a potential 'Tone Shift' or mismatch between specific negative descriptors and general positive outlook. Should focus on the Q&A section for reveal. Should mention uncertainty mapping (tracking 'challenging', 'headwinds'). Should provide a Sentiment Scorecard.
+
+## File-driven variant
+
+With fixture(s) `evals/files/earnings_call_excerpt.txt`:
+
+> Analyze the attached earnings-call excerpt (evals/files/earnings_call_excerpt.txt): overall tone, the specific hedging/uncertainty language, the quantitative signals that cut against the positive headline, and what a sentiment model should weight most.
+
+Expected: Surface tone positive (record OCF, 18% growth, guidance reiterated) but hedged: 'prudent to assume', 'admittedly uncertain', 'yet'. Negative quant signals: contract assets growing faster than revenue, DSO +6 days, inventory build, margin low-end cut 50bps, deal discounting. Net: cautiously positive with deteriorating quality-of-revenue markers.

package/selected-skills/financeskills/skills/nlp-earnings-sentiment/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: nlp-earnings-sentiment
+description: When the user wants to analyze earnings call transcripts or financial news for sentiment shifts. Also use when the user mentions "analyzing earnings calls," "management tone," "sentiment score," "Q&A analysis," "detecting bullishness," or "transcripts NLP."
+metadata:
+  version: 1.0.0
+---
+
+# NLP Earnings Sentiment
+
+You are an AI Quant Analyst. Your goal is to use Natural Language Processing to detect subtle shifts in management confidence that quantitative data might miss.
+
+## Initial Assessment
+
+1. **Source Material**
+   - Do we have the full transcript of the earnings call?
+   - Do we have transcripts from the previous 4 quarters for comparison?
+
+2. **Target Metrics**
+   - Are we looking at the "Prepared Remarks" or the "Q&A Section"? (Q&A is often more revealing).
+
+---
+
+## NLP Framework
+
+### Technical Limitation
+**Context Matters.**
+Generic sentiment libraries (like VADER) often fail in finance because words like "tax" or "cost" are neutral/standard but labeled as negative. This skill uses **FinBERT** or custom financial lexicons.
+
+### Priority Order
+1. **Linguistic Pre-processing** (Cleaning transcripts, removing legal disclaimers).
+2. **Sentiment Scoring** (Applying financial-specific NLP models).
+3. **Comparative Analysis** (Measuring "Tone Shift" vs. previous quarters).
+4. **Keyword Extraction** (Identifying what management is talking about *more* or *less*).
+
+---
+
+## Technical NLP Steps
+
+### 1. Tone Shift Detection
+- Calculate the ratio of positive to negative words in the Q&A section. 
+- Compare this ratio to the historical average for this management team.
+
+### 2. Uncertainty Mapping
+- Track the frequency of words like "uncertain," "volatile," "might," and "assume." 
+- A spike in these words often precedes a stock price correction.
+
+### 3. Management vs. Analyst Sentiment
+- Compare the sentiment of management's answers to the sentiment of the analysts' questions to detect friction.
+
+---
+
+## Output Format
+
+### Sentiment Analysis Report Structure
+
+**Sentiment Scorecard**
+- **Overall Score**: (e.g., +0.75 - Very Bullish).
+- **Tone Shift**: (e.g., -15% decline from last quarter).
+
+**Key Findings**
+- Top 3 "Stress Points" discussed in the Q&A.
+- Areas where management was unusually vague or evasive.
+
+**Quantitative Overlay**
+- Correlation between sentiment shifts and stock price movement in previous quarters.
+
+---
+
+## References
+- [FinBERT Overview](./references/finbert-guide.md): Why specialized models matter.
+- [Tone Analysis Basics](./references/linguistic-finance.md): Detecting management evasiveness.
+
+---
+
+## Related Skills
+- **investment-analysis**: To add qualitative context to a valuation.
+- **financial-analysis**: To see if the sentiment aligns with the hard numbers.

package/selected-skills/financeskills/skills/nlp-earnings-sentiment/references/finbert-guide.md

@@ -0,0 +1,26 @@
+# FinBERT and Financial NLP Models
+
+## Why Domain Models
+General sentiment models misread finance: "liability decreased" is positive; "beat expectations despite headwinds" is positive; "in line with guidance" is neutral-positive. Finance-tuned models (FinBERT variants, e.g., ProsusAI/finbert, yiyanghkust/finbert-tone) are trained on analyst reports and earnings text.
+
+## Usage Pattern
+```python
+from transformers import pipeline
+clf = pipeline("text-classification", model="yiyanghkust/finbert-tone")
+scores = clf(sentences)   # labels: Positive / Negative / Neutral
+```
+- Sentence-level scoring, then aggregate: `net tone = (pos − neg) / total sentences`.
+- Chunk transcripts ≤ 512 tokens; split on sentence boundaries, never mid-sentence.
+
+## Earnings Call Structure Matters
+- **Prepared remarks**: scripted, uniformly positive — low signal. Compare vs. the company's own historical baseline, not absolute tone.
+- **Q&A section**: highest signal. Analyze separately. Evasive answers (deflection, non-answers, "we don't guide on that") and question-answer tone gaps are stronger predictors than raw sentiment.
+- Track **tone delta vs. prior quarters**, not levels.
+
+## Beyond Sentiment
+- Hedging density: counts of "approximately", "we believe", "subject to" per 100 words.
+- Numeric specificity: ratio of quantified statements to total claims (specificity drops before bad news).
+- Topic shift: new risk topics vs. prior call (embedding distance per section).
+
+## Validation
+Backtest tone deltas against post-call abnormal returns or subsequent guidance revisions before trusting any signal. Report correlation, not causation.

package/selected-skills/financeskills/skills/nlp-earnings-sentiment/references/linguistic-finance.md

@@ -0,0 +1,23 @@
+# Linguistic Markers in Financial Disclosure
+
+## Loughran-McDonald Word Lists (the finance standard)
+General-purpose lexicons (Harvard-IV) misclassify ~75% of finance "negative" words (e.g., "tax", "cost", "liability" are routine). Use L-M categories:
+- **Negative** (loss, impairment, litigation, restated), **Positive** (achieve, improve, strong), **Uncertainty** (approximately, contingent, may), **Litigious** (claimant, plaintiff), **Weak/Strong modal** (could/might vs. will/must), **Constraining** (covenant, restrict).
+
+Metric: `category density = category word count / total words`, compared against the same company's history and sector peers.
+
+## Documented Red-Flag Patterns (research-backed)
+1. **Rising uncertainty + weak modal density** ahead of negative revisions.
+2. **Fog/complexity increase**: longer sentences, more passive voice in 10-K MD&A precede underperformance (Li 2008).
+3. **Pronoun shifts**: "I/we" ownership language dropping in favor of impersonal constructions during deteriorating quarters.
+4. **Disclosure length spikes** in risk factors and critical accounting estimates sections.
+5. **Non-answers in Q&A**: answer length ≪ question complexity; topic deflection.
+6. **Scripted Q&A**: unusually fluent answers to hostile questions (pre-seeded questions).
+
+## Quantitative Measures
+- Gunning Fog index on MD&A year-over-year.
+- Cosine similarity of consecutive 10-K risk sections: a sudden DROP means new risks added — read the diff.
+- Negation handling: "not expecting growth" — apply 3-word negation windows when using lexicons.
+
+## Caveats
+Language signals are weak individually; combine ≥ 3 markers and always tie to the numbers (does tone diverge from reported results? divergence IS the signal).

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)