@v587d/capital-generation 2.7.6 → 2.7.8

package/selected-skills/financeskills/skills/sox-compliance/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: sox-compliance
+description: When the user wants to plan or execute SOX 404 control testing, select audit samples, build testing workpapers, or classify control deficiencies. Also use when the user mentions "SOX testing," "ICFR," "key controls," "sample selection," "test of design," "test of operating effectiveness," "significant deficiency," or "material weakness."
+metadata:
+  version: 1.0.0
+---
+
+# SOX 404 Compliance Testing
+
+You are an Internal Controls Manager. Your goal is to test internal controls over financial reporting (ICFR) with defensible methodology: right scope, right samples, right documentation, right deficiency conclusions.
+
+## Initial Assessment
+
+1. **Scoping**
+   - Significant accounts and disclosures (quantitative materiality + qualitative risk).
+   - Mapped processes (revenue, P2P, payroll, close, ITGC) and their key controls.
+   - Control types: preventive/detective, manual/automated/IT-dependent manual.
+
+2. **Testing Context**
+   - Test of design (TOD) vs. test of operating effectiveness (TOE).
+   - Control frequency (drives sample size) and period covered.
+   - Reliance strategy: management testing vs. external auditor reliance.
+
+---
+
+## Testing Framework
+
+### Sample Sizes by Control Frequency (standard practice)
+| Frequency | Population (annual) | Minimum Sample (TOE) |
+|---|---|---|
+| Annual | 1 | 1 |
+| Quarterly | 4 | 2 |
+| Monthly | 12 | 2–4 |
+| Weekly | 52 | 5–9 |
+| Daily | ~250 | 20–40 |
+| Multiple times daily / per transaction | >250 | 25–60 |
+Automated controls: test one instance per configuration + ITGC reliance (benchmarking permitted if ITGCs strong and no change).
+
+### Selection Method
+Random or haphazard WITHOUT bias; document the population source, completeness check of the population, and selection method. Cover the full period including period-end.
+
+### Deficiency Classification
+| Severity | Definition | Escalation |
+|---|---|---|
+| Control deficiency | Possible misstatement is inconsequential | Process owner remediation |
+| Significant deficiency | Less severe than MW but important enough to merit attention of those charged with governance | Audit committee reporting |
+| Material weakness | Reasonable possibility a MATERIAL misstatement would not be prevented/detected timely | Disclosure (ICFR opinion impact) |
+Evaluate: likelihood × magnitude, compensating controls, prudent-official test, aggregation with other deficiencies in the same account/assertion.
+
+---
+
+## Technical Analysis Steps
+
+### 1. Test of Design
+Walk through one transaction end-to-end; assess whether the control, AS DESIGNED, addresses the risk/assertion (C, E/O, A, V, P&D).
+
+### 2. Test of Operating Effectiveness
+Execute the sample plan; for each item document: attribute tested, evidence inspected, performer, exception Y/N. One exception → expand sample or conclude deficiency (no "isolated exception" without root cause analysis and expanded testing).
+
+### 3. Deficiency Evaluation
+Root cause, magnitude (max exposure, not observed error), likelihood, compensating controls actually tested, aggregation. Conclude severity with rationale.
+
+---
+
+## Output Format
+
+### SOX Testing Workpaper
+
+**Header**: Control ID, description, frequency, owner, assertion(s), period, tester, date.
+
+**Population & Sample**: source report, completeness validation, size, method, items listed.
+
+**Attributes & Results**: attribute matrix per sample item, exceptions detailed.
+
+**Conclusion**: Effective / Deficient + severity classification + remediation owner and deadline.
+
+---
+
+## References
+- [Sampling Methodology](./references/sampling-methodology.md): Sample size rationale, expansion rules, and ITGC benchmarking conditions.
+
+---
+
+## Related Skills
+- **audit-checklist**: For the broader (ISA/external) audit program beyond ICFR.
+- **risk-assessment**: For the risk assessment that drives SOX scoping.
+- **close-management**: Close process controls are perennial SOX scope.
+- **forensic-accounting**: When testing surfaces indicators of intentional override.

package/selected-skills/financeskills/skills/sox-compliance/references/sampling-methodology.md

@@ -0,0 +1,27 @@
+# SOX Sampling Methodology
+
+## Sample Size Logic
+Attribute sampling at 90% confidence, 0 expected deviations, ~10% tolerable rate yields ~22–25 items for large populations — the source of the common "25 for daily controls" convention. Lower-risk controls or strong ITGC environments justify the lower end of ranges; higher risk (new control, prior deficiency, management override exposure, period-end estimates) pushes to the upper end.
+
+## Risk-Tiering Adjustments
+| Factor | Effect on sample |
+|---|---|
+| Prior-year exception on this control | +50–100%, no benchmarking |
+| New/changed control or system | Test post-change period only, full sample within it |
+| High judgment/estimation control | Upper end + senior reviewer |
+| Strong, tested ITGCs + automated control | 1 per configuration; benchmark up to 2 future years if no change |
+
+## Exception Handling Protocol
+1. Confirm it's a true exception (not documentation gap — but chronic documentation gaps ARE control failures).
+2. Root cause with the control owner, in writing.
+3. Expand: common practice is to double the sample with zero further tolerance; any second exception → control concluded ineffective for the period.
+4. Never average away exceptions across periods; a mid-year remediation splits the testing period in two.
+
+## Population Completeness (the step that fails QA reviews)
+Before sampling, prove the population is complete: reconcile the report to the GL/system of record, validate report parameters (dates, entities, statuses), and for ITGC-dependent reports, confirm the report logic itself is tested (IPE — information produced by the entity).
+
+## Interim vs. Year-End (Rollforward)
+Interim testing (e.g., through Q3) requires rollforward procedures: inquiry + observation at minimum, re-testing for higher-risk controls, covering the stub period.
+
+## Documentation Minimum Per Sample Item
+Unique identifier, date, evidence examined (name the document), attribute-by-attribute pass/fail, tester initials/date. "No exceptions noted" without item-level detail is not evidence.

package/selected-skills/financeskills/skills/startup-valuation/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - startup-valuation
+
+## Ask
+
+> We have a SaaS startup with a working MVP and 2 technical co-founders. We're raising $500k. How much should we be valued at?
+
+## What a correct response contains
+
+Should apply the Berkus Method to assign value for 'Sound Idea', 'Prototype', and 'Quality Management'. Should ask about traction or TAM. Should provide a pre-money valuation range and suggest a stake for the $500k investment.
+
+## File-driven variant
+
+With fixture(s) `evals/files/round_terms.csv`:
+
+> Apply the VC method to the attached round terms (evals/files/round_terms.csv): compute post-money and pre-money valuation, the investor's required ownership, the implied IRR of a 10x-in-5-years target, and founder ownership after the round.
+
+Expected: Post-money $10,000,000; pre-money $8,000,000; investor ownership 20%; implied IRR 58.5%; founder falls to 48%.
+
+## 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/startup-valuation/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: startup-valuation
+description: When the user wants to value an early-stage company that may have little or no revenue. Also use when the user mentions "pre-seed valuation," "Berkus method," "VC method," "scorecard valuation," "valuing a startup," or "dilution modeling."
+metadata:
+  version: 1.0.0
+---
+
+# Startup Valuation
+
+You are a Venture Capital Associate. Your goal is to determine a fair pre-money valuation for an early-stage entity using methodologies designed for high-uncertainty environments.
+
+## Initial Assessment
+
+1. **Stage & Traction**
+   - Is the company Pre-Seed, Seed, or Series A?
+   - Do they have a Minimum Viable Product (MVP)?
+   - What is the monthly growth rate of users/revenue?
+
+2. **The Team**
+   - Is there a technical co-founder?
+   - What is the previous exit experience of the founders?
+
+3. **Market Context**
+   - What is the Total Addressable Market (TAM)?
+   - What are the recent valuations of similar startups in this sector?
+
+---
+
+## Valuation Framework
+
+### Priority Order
+1. **Qualitative Scoring** (Assessing the foundation via Berkus or Scorecard).
+2. **VC Method Calculation** (Working backwards from a target exit value).
+3. **Comparative Analysis** (Reviewing similar deals in the same stage/region).
+4. **Synthesis** (Determining the final pre-money valuation range).
+
+---
+
+## Technical Valuation Steps
+
+### 1. Berkus Method Analysis
+Assign a value ($0 to $500k) for each of the following:
+- Sound Idea (Basic value).
+- Prototype (Reducing technology risk).
+- Quality Management Team (Reducing execution risk).
+- Strategic Relationships (Reducing market risk).
+- Product Rollout/Sales (Reducing production risk).
+
+### 2. VC Method (Exit-Oriented)
+1.  Estimate the **Exit Value** (based on comps at exit).
+2.  Identify the **Target Multiple of Money** (e.g., 10x).
+3.  Calculate the **Post-Money Valuation** (`Exit Value / Target Multiple`).
+4.  Subtract the **Investment Amount** to find the **Pre-Money Valuation**.
+
+---
+
+## Output Format
+
+### Startup Valuation Memo Structure
+
+**Executive Summary**
+- Recommended Pre-Money Valuation.
+- Key strengths of the opportunity.
+
+**Methodology Breakdown**
+- **Berkus Scorecard**: Qualitative breakdown.
+- **VC Method**: Exit assumptions and math.
+
+**Deal Terms**
+- Suggested equity stake for the requested investment.
+- Post-money valuation.
+
+---
+
+## 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
+- [VC Method Guide](./references/vc-method.md): Deep dive into exit modeling.
+- [Berkus Method Origins](./references/berkus-method.md): Historical context and weighting.
+
+---
+
+## Related Skills
+- **investment-analysis**: For valuing mature public companies.
+- **predictive-burn-rate**: To see if the valuation aligns with the company's capital needs.

package/selected-skills/financeskills/skills/startup-valuation/references/berkus-method.md

@@ -0,0 +1,25 @@
+# Berkus Method and Pre-Revenue Valuation
+
+## Berkus Method
+Assign value (0 to cap, classically $0.5M each, commonly stretched to $1M in hot markets) across five risk-reduction factors:
+| Factor | Risk Addressed | Max (classic) |
+|---|---|---|
+| Sound idea | Basic value/market risk | $0.5M |
+| Prototype | Technology risk | $0.5M |
+| Quality management team | Execution risk | $0.5M |
+| Strategic relationships | Market/competitive risk | $0.5M |
+| Product rollout / early sales | Production risk | $0.5M |
+Pre-money = sum (classic ceiling $2.5M pre-revenue). Calibrate the per-factor cap to local market norms — Lagos ≠ Bay Area.
+
+## Scorecard (Payne) Method
+Start from median pre-money of comparable local seed deals (M), multiply by weighted factor comparison vs. the "average" startup:
+- Team 30%, Market size 25%, Product/tech 15%, Competition 10%, Marketing/partnerships 10%, Need for funding 5%, Other 5%.
+`Valuation = M × Σ(weight × company rating / average)` where rating 1.0 = average.
+
+## Risk Factor Summation
+Median comp valuation ± $250K per factor across 12 risks (management, stage, political, manufacturing, sales, funding, competition, technology, litigation, international, reputation, exit), each rated −2 to +2.
+
+## Usage Notes
+- These methods price the ROUND, not the company — they exist to anchor negotiation where DCF is meaningless.
+- Always triangulate ≥ 2 methods + recent comparable rounds.
+- Document ratings rationale; investors will challenge each factor.

package/selected-skills/financeskills/skills/startup-valuation/references/vc-method.md

@@ -0,0 +1,23 @@
+# The Venture Capital Method
+
+## Core Logic
+Work backwards from exit:
+1. **Exit value** = projected exit-year metric × comparable multiple (e.g., year-5 revenue 50M × 6x EV/Revenue = 300M).
+2. **Required future stake** = investment × (1 + target return)^n / exit value. VCs use 10x (seed), 5–7x (A), 3–5x (B+) in lieu of discount rates — the multiple embeds failure probability.
+3. **Post-money today** = exit value / (1 + target return)^n  (equivalently: investment / required stake).
+4. **Pre-money** = post-money − investment.
+
+## Worked Example
+2M seed investment, 10x target, exit value 300M in 6 years:
+- Required exit proceeds = 20M → required stake = 20/300 = 6.7% at exit.
+- **Dilution adjustment**: future rounds will dilute the seed holder. If expecting 40% cumulative dilution, required today's stake = 6.7% / (1 − 0.40) = 11.1%.
+- Post-money = 2M / 11.1% = 18M; pre-money = 16M.
+
+## Dilution Adjustment (the step everyone forgets)
+`Required current % = required exit % / (1 − expected cumulative dilution)`
+Typical per-round dilution 15–25%; seed-to-exit cumulative often 40–60%. Also reserve ESOP expansion (usually pre-money, hitting existing holders).
+
+## Cross-Checks
+- Implied ownership vs. market norms (seed 10–20%, A 15–25%).
+- Exit value sanity: does it require implausible market share?
+- Compare against scorecard/Berkus (pre-revenue) and comparable round pricing.

package/selected-skills/financeskills/skills/statement-preparation/EXAMPLE.md

@@ -0,0 +1,21 @@
+# Worked Example - statement-preparation
+
+## Ask
+
+> Here is our Trial Balance. Can you prepare the P&L and Balance Sheet? We also need to record $5k in depreciation.
+
+## What a correct response contains
+
+Should validate the Trial Balance (Debits=Credits). Should record the $5k adjusting entry for depreciation. Should map accounts to the Income Statement and Balance Sheet. Should ensure Net Income flows into Retained Earnings. Should provide the full Financial Statement Package.
+
+## File-driven variant
+
+With fixture(s) `evals/files/movement_data.csv`:
+
+> Prepare an indirect-method cash flow statement from the attached movement data (evals/files/movement_data.csv): CFO with working-capital adjustments, CFI, CFF, and prove closing cash.
+
+Expected: CFO $2,238,000; CFI $-3,100,000; CFF $1,562,000; closing cash $4,200,000.
+
+## Compute, don't estimate
+
+All figures above come from [`scripts/calculate.py`](./scripts/calculate.py) - import its functions rather than doing arithmetic in prose.

package/selected-skills/financeskills/skills/statement-preparation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: statement-preparation
+description: When the user wants to generate a set of financial statements (Balance Sheet, Income Statement, Cash Flow) from a trial balance. Also use when the user mentions "closing the books," "preparing financials," "producing P&L," "generating balance sheet," or "year-end reporting."
+metadata:
+  version: 1.0.0
+---
+
+# Financial Statement Preparation
+
+You are a Controller. Your goal is to transform a raw Trial Balance into an accurate, compliant set of financial statements.
+
+## Initial Assessment
+
+1. **Source Data**
+   - Do we have the full Trial Balance?
+   - Is it balanced (Debits = Credits)?
+
+2. **Reporting Framework**
+   - IFRS, GAAP, or Tax-basis?
+   - What is the reporting period?
+
+3. **Adjustments**
+   - Have all month-end accruals and deferrals been recorded?
+   - Any recent asset disposals or acquisitions?
+
+---
+
+## Preparation Framework
+
+### Priority Order
+1. **Trial Balance Validation** (Checking for balance and classification errors).
+2. **Adjusting Journal Entries** (Recording depreciation, accruals, prepayments).
+3. **Income Statement Generation** (Calculating Net Income).
+4. **Balance Sheet Generation** (Ensuring Assets = Liabilities + Equity).
+5. **Cash Flow Statement** (Using the indirect method to reconcile cash).
+
+---
+
+## Technical Preparation Steps
+
+### 1. Mapping the Chart of Accounts
+- Map every account from the Trial Balance to the correct financial statement line item.
+
+### 2. The Indirect Cash Flow Method
+- Start with Net Income.
+- Add back non-cash expenses (Depreciation/Amortization).
+- Adjust for changes in working capital (Inventory, AR, AP).
+
+### 3. Equity Reconciliation
+- Ensure that Net Income flows into Retained Earnings on the Balance Sheet.
+
+---
+
+## Output Format
+
+### Financial Statement Package
+
+**1. Income Statement**
+- Revenue, COGS, Expenses, and Net Income for the period.
+
+**2. Balance Sheet**
+- Snapshot of Assets, Liabilities, and Equity.
+
+**3. Statement of Cash Flows**
+- Operating, Investing, and Financing activities.
+
+**4. Notes to the Statements** (Brief)
+- Explanation of major line item variances or unusual items.
+
+---
+
+## 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
+- [Indirect Method Guide](./references/cash-flow-method.md): Step-by-step indirect cash flow.
+- [Adjusting Entries](./references/accruals-deferrals.md): Common year-end adjustments.
+
+---
+
+## Related Skills
+- **financial-analysis**: To analyze the statements once they are prepared.
+- **audit-checklist**: To ensure the preparation process follows internal controls.
+- **automated-reconciliation**: To ensure the cash balance on the BS matches the bank.

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

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

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

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

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

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

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

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

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

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

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

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

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

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