@v587d/capital-generation 2.7.6 → 2.7.8

package/selected-skills/financeskills/skills/lbo-modeling/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: lbo-modeling
+description: When the user wants to model a Leveraged Buyout (LBO) for private equity analysis. Also use when the user mentions "private equity model," "debt capacity analysis," "exit IRR," "MOIC calculation," "sources and uses," or "entry multiple."
+metadata:
+  version: 1.0.0
+---
+
+# LBO Modeling
+
+You are a Private Equity Associate. Your goal is to determine if a company is a viable LBO candidate by modeling debt repayment, cash flow generation, and exit returns (IRR/MOIC).
+
+## Initial Assessment
+
+1. **Transaction Context**
+   - What is the Entry Multiple (e.g., 10x EBITDA)?
+   - What is the estimated Exit Multiple?
+   - What is the target holding period (usually 3-7 years)?
+
+2. **Financing Assumptions**
+   - How much debt can the company support (Debt/EBITDA)?
+   - What are the interest rates for different tranches (Senior, Mezzanine)?
+
+3. **Operations & Growth**
+   - What is the projected EBITDA growth?
+   - What are the ongoing CapEx requirements?
+
+---
+
+## LBO Framework
+
+### Priority Order
+1. **Sources & Uses** (Calculating the total purchase price and how it's funded).
+2. **Operations Forecast** (Projecting Revenue to Free Cash Flow).
+3. **Debt Schedule** (Modeling the mandatory and optional repayment of debt).
+4. **Returns Analysis** (Calculating Internal Rate of Return (IRR) and Multiple of Invested Capital (MOIC)).
+5. **Sensitivity Analysis** (Testing returns against entry/exit multiples and growth rates).
+
+---
+
+## Technical Modeling Steps
+
+### 1. Sources & Uses Table
+- **Uses**: Purchase Equity, Refinance Existing Debt, Transaction Fees.
+- **Sources**: New Debt, Sponsor Equity.
+
+### 2. Cash Flow for Debt Service (CFADS)
+- Calculate EBITDA -> Less Taxes -> Less Interest -> Less CapEx -> Less Δ Working Capital.
+- This represents the cash available to pay down principal.
+
+### 3. IRR Calculation
+- `IRR = (Exit Proceeds / Entry Equity)^(1/n) - 1`.
+- MOIC (Multiple of Money) = `Exit Proceeds / Entry Equity`.
+
+---
+
+## Output Format
+
+### LBO Analysis Summary
+
+**The Deal**
+- Total Transaction Value.
+- Equity Contribution vs. Debt Funding.
+
+**The Returns (Base Case)**
+- **IRR**: (e.g., 22.5%).
+- **MOIC**: (e.g., 2.4x).
+- Exit Date: (e.g., Year 5).
+
+**Returns Matrix**
+- Table showing IRR across different Exit Multiples and Revenue Growth scenarios.
+
+---
+
+## Scripts
+- [calculate.py](./scripts/calculate.py): Sources & uses, cash sweep debt schedule, and IRR/MoM functions. Run with `python3 scripts/calculate.py` to self-test; import the functions for actual computations.
+
+---
+
+## References
+- [LBO Modeling Standards](./references/lbo-best-practices.md): Industry conventions.
+- [Debt Tranches Explained](./references/debt-structures.md): Senior vs. Subordinated.
+
+---
+
+## Related Skills
+- **investment-analysis**: For the baseline business quality assessment.
+- **financial-analysis**: For auditing the EBITDA sustainability.
+- **risk-assessment**: For evaluating the bankruptcy risk of high leverage.

package/selected-skills/financeskills/skills/lbo-modeling/references/debt-structures.md

@@ -0,0 +1,22 @@
+# LBO Debt Structures
+
+## Typical Capital Stack (top = paid first)
+| Tranche | Leverage | Pricing (indicative) | Features |
+|---|---|---|---|
+| Revolver | undrawn at close | SOFR + 200–350 | Liquidity backstop; springing covenant |
+| Term Loan A | with TLB, 0.5–1.5x | SOFR + 250–350 | Bank-held, 5–10% annual amortization |
+| Term Loan B | 3–4.5x cumulative | SOFR + 350–500, 0–0.5% floor | Institutional, 1% amort, covenant-lite common |
+| Senior Notes / High Yield | +1–2x | Fixed 7–10% | No amort, call protection (NC-2/3) |
+| Mezzanine / PIK | +0.5–1x | 11–14% cash+PIK | Warrants sometimes attached |
+| Sponsor Equity | 40–60% of capital | — | Residual claim |
+
+## Key Terms to Model
+- **Amortization**: TLA meaningful; TLB 1%/yr; notes bullet.
+- **Cash sweep / ECF sweep**: % of excess cash flow, often leverage-ratcheted.
+- **PIK toggle**: interest accrues to principal — compounds against the exit equity.
+- **Call protection**: HY non-call periods and premiums (e.g., 105/102.5/100) matter for refi scenarios.
+- **Covenants**: maintenance (leverage, coverage — tested quarterly, TLA/revolver) vs. incurrence (HY). Model headroom ≥ 15–25% cushion to projections.
+- **OID & financing fees**: amortize into interest expense (effective yield); add cash cost at close.
+
+## Structuring Logic
+More TLA/amortizing debt = faster deleveraging, better IRR from paydown but tighter covenants. More HY/PIK = flexibility, higher cost, returns lean on growth. Match amortization burden to FCF stability of the business.

package/selected-skills/financeskills/skills/lbo-modeling/references/lbo-best-practices.md

@@ -0,0 +1,27 @@
+# LBO Modeling Best Practices
+
+## Model Architecture (order matters)
+1. Transaction assumptions: entry EV (multiple × LTM EBITDA), sources & uses, fees.
+2. Debt schedule with mandatory amortization + cash sweep.
+3. Integrated 3-statement projection (or EBITDA-to-FCF bridge for quick models).
+4. Exit: exit multiple × exit-year EBITDA → equity proceeds → IRR/MoM.
+5. Sensitivities: entry/exit multiple grid, leverage grid, growth/margin grid.
+
+## Sources & Uses Discipline
+- Uses: equity purchase price + refinanced debt + transaction fees (2–3% of EV) + financing fees (2–3% of debt, capitalized and amortized).
+- Sources: each debt tranche + sponsor equity + management rollover. Must balance to the dollar.
+- Minimum cash to balance sheet — never fund the deal to zero cash.
+
+## Cash Sweep Mechanics
+`FCF available = EBITDA − cash interest − cash taxes − capex − ΔNWC − mandatory amort`
+Sweep order: revolver first, then tranches by seniority (check covenants — some TLBs have 50%/25%/0% ECF sweep tiers by leverage).
+
+## Returns Math
+- `MoM = Exit equity / Entry equity`; `IRR = MoM^(1/years) − 1` for single-flow deals.
+- Value creation bridge at exit: EBITDA growth + multiple expansion + debt paydown = total equity gain. Attribute every deal — if returns are mostly multiple expansion, the thesis is market beta.
+- Target: 20–25% IRR / 2.0–3.0x MoM over 5 years.
+
+## Sanity Checks
+- Leverage: 4–6x total debt/EBITDA typical; interest coverage (EBITDA/cash interest) ≥ 2x in all projection years.
+- Credit stats improve over hold or the model has a problem.
+- Circularity (interest ↔ cash) — use opening-balance interest convention or iterative solve; document which.

package/selected-skills/financeskills/skills/lease-accounting/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - lease-accounting
+
+## Ask
+
+> We signed a 5-year office lease: 10,000,000 NGN per year paid annually in arrears, IBR 18%, no incentives, no restoration. Compute the initial lease liability and ROU asset and give me year-1 entries.
+
+## What a correct response contains
+
+Liability = PV of 5 payments of 10M at 18% = ~31,272,000 NGN. ROU = same. Year 1: interest = ~5,629,000, payment 10M reduces liability to ~26,901,000; ROU depreciation = ~6,254,400/yr straight-line.
+
+## File-driven variant
+
+With fixture(s) `evals/files/lease_portfolio.csv`:
+
+> Using the attached lease portfolio (evals/files/lease_portfolio.csv) — payments annual in arrears, no renewal options, commencement today — measure each lease liability and right-of-use asset at commencement under IFRS 16, and compute total year-1 interest expense and straight-line depreciation. Produce a commencement summary table and the initial journal entry.
+
+Expected: Liabilities: L-01 $1,025,049, L-02 $689,597, L-03 $194,383; total $1,909,029 (ROU assets equal liabilities here). Year-1 interest $144,416; year-1 depreciation $339,805.
+
+## 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/lease-accounting/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: lease-accounting
+description: When the user wants to account for leases under IFRS 16 or ASC 842. Also use when the user mentions "right-of-use asset," "lease liability," "incremental borrowing rate," "lease modification," "operating vs finance lease," "lease term," or "embedded lease."
+metadata:
+  version: 1.0.0
+---
+
+# Lease Accounting (IFRS 16 / ASC 842)
+
+You are a Technical Accounting Manager. Your goal is to identify, measure, and account for leases correctly — initial recognition, subsequent measurement, modifications, and disclosure.
+
+## Initial Assessment
+
+1. **Lease Identification**
+   - Is there an identified asset (explicit or implicit, no substantive substitution right)?
+   - Does the customer control the use (direct how/for what purpose) and obtain substantially all economic benefits?
+   - Check embedded leases in service/outsourcing/transport/storage contracts.
+
+2. **Measurement Inputs**
+   - Lease term: non-cancellable period + reasonably certain extension/termination options.
+   - Payments: fixed, in-substance fixed, index-linked variable (in), usage-based variable (out), residual guarantees, purchase options.
+   - Discount rate: rate implicit in lease, else incremental borrowing rate (IBR).
+
+---
+
+## Accounting Framework
+
+### Initial Recognition (lessee)
+- `Lease liability = PV of unpaid lease payments at the discount rate`
+- `ROU asset = liability + prepaid payments + initial direct costs + restoration estimate − incentives received`
+
+### Subsequent Measurement
+- Liability: effective interest method (interest = opening balance × rate; payments reduce balance).
+- ROU asset: depreciate straight-line over shorter of lease term and useful life (to useful life if ownership transfers/purchase option reasonably certain).
+- IFRS 16: single model. ASC 842: finance leases as above; operating leases keep single straight-line lease cost (liability math identical).
+
+### Exemptions
+Short-term (≤ 12 months, no purchase option) and low-value assets (IFRS only, ~$5k new): expense straight-line. Apply policy consistently and disclose.
+
+### Reassessment & Modifications
+- Index/rate change → remeasure liability against ROU (unchanged discount rate).
+- Term/option reassessment → remeasure with REVISED discount rate.
+- Modification adding asset at market rate → separate lease. Scope decrease → reduce ROU proportionately, gain/loss to P&L. Other modifications → remeasure against ROU.
+
+---
+
+## Technical Analysis Steps
+
+1. **Build the amortization schedule** — period, opening liability, interest, payment, closing liability; parallel ROU depreciation track. Verify with code.
+2. **Classify P&L and cash flow effects** — depreciation + interest (IFRS); principal → financing, interest → policy choice (IFRS) / operating (US GAAP).
+3. **Transition/portfolio checks** — consistent IBR matrix by currency/term; completeness sweep of contracts > 12 months.
+
+---
+
+## Output Format
+
+### Lease Accounting Memo
+
+**Conclusion**: lease/not a lease; classification (US GAAP); exemptions applied.
+
+**Measurement**: inputs table (term, rate, payments), initial liability and ROU values.
+
+**Schedule**: full amortization table + annual JE summary.
+
+**Judgments**: option assessments, IBR derivation, variable payment treatment.
+
+---
+
+## 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
+- [IBR Determination](./references/ibr-guide.md): Building incremental borrowing rates defensibly.
+
+---
+
+## Assets
+- [commencement-summary-template.md](./assets/commencement-summary-template.md): Portfolio measurement and journal entry template.
+
+---
+
+## Related Skills
+- **journal-entry**: For the monthly lease entries.
+- **aro-computation**: Restoration obligations attached to leased sites.
+- **statement-preparation**: Lease presentation and disclosure in statements.
+- **deferred-tax**: ROU/liability temporary differences.

package/selected-skills/financeskills/skills/lease-accounting/assets/commencement-summary-template.md

@@ -0,0 +1,28 @@
+# Lease Commencement Summary (IFRS 16 / ASC 842)
+
+**Lessee:** {entity} | **Commencement:** {date} | **Discount basis:** {IBR / implicit rate}
+
+## Portfolio Measurement
+| Lease | Asset | Payment | Timing | Term | Rate | Lease liability | ROU asset |
+|---|---|---|---|---|---|---|---|
+| | | | arrears/advance | | | | |
+| **Total** | | | | | | **{x}** | **{x}** |
+
+{ROU = liability + prepaid + initial direct costs + dismantling - incentives. State any differences.}
+
+## Year-1 P&L Impact
+| Lease | Interest expense | Depreciation | Total | vs old operating-lease rent |
+|---|---|---|---|---|
+
+## Initial Journal Entry
+| Account | Dr | Cr |
+|---|---|---|
+| Right-of-use asset | {x} | |
+| Lease liability | | {x} |
+
+## Judgments
+- Renewal/termination options {included/excluded - why}
+- Short-term / low-value exemptions applied: {list}
+
+---
+*Present values computed with scripts/calculate.py. AI-prepared - review required.*

package/selected-skills/financeskills/skills/lease-accounting/references/ibr-guide.md

@@ -0,0 +1,26 @@
+# Incremental Borrowing Rate (IBR) Determination
+
+## Definition
+The rate the lessee would pay to borrow, over a similar term, with similar security, the amount needed to obtain an asset of similar value in a similar economic environment. It is lease-specific, not the company's WACC and not its existing average debt cost.
+
+## Build-Up Approach (the auditable method)
+`IBR = Reference rate (currency + term matched) + Credit spread (entity, secured basis) + Asset/security adjustment`
+
+1. **Reference rate**: government bond yield in the lease currency, tenor ≈ weighted-average lease payment timing (duration, not full term). NGN leases → FGN bond curve; USD → Treasury curve.
+2. **Credit spread**: from the entity's traded debt, recent loan pricing, or rating-implied spread matrix. Subsidiaries: stand-alone credit unless parent guarantee exists in the lease.
+3. **Security adjustment**: leases are effectively secured borrowing → deduct an unsecured-to-secured adjustment (commonly 20–60 bps; property leases at the higher security end).
+
+## Portfolio Practicalities
+- Build an IBR matrix: currency × term bucket (1–3y, 3–5y, 5–10y, 10y+) × entity, refreshed quarterly; apply to new leases by bucket.
+- Document the date of each rate — IBR is set at commencement (or modification), not reporting date.
+- Materiality shortcut: portfolio-level rate permitted for similar leases (IFRS 16.B1).
+
+## Common Audit Findings
+1. Using WACC or a flat round number across all leases.
+2. Term mismatch (10-year lease at a 1-year rate).
+3. Currency mismatch (USD rate on NGN-denominated payments — the inflation differential makes this badly wrong).
+4. Stale rates applied to new commencements after a rate environment shift.
+5. No security adjustment documentation.
+
+## Sensitivity
+Disclose/monitor: ±100 bps typically moves the liability ~4–8% on a 10-year lease. High-rate environments (NGN) make the discounting effect dramatic — a 10-year NGN lease at 18% discounts late-year payments to very little.

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).