phoenix-xirr-fees-validator
Validation for XIRR and fee calculations. Use when working on server/analytics/xirr.ts, server/analytics/fees.ts, or their truth cases.
When & Why to Use This Skill
This Claude skill provides robust validation for XIRR and fee calculations, ensuring software implementations align with Excel parity and predefined truth cases. It streamlines the debugging and refactoring of financial analytics code by automating consistency checks for cash-flow IRR, sign conventions, and complex fee schedules, making it an essential tool for fintech developers and QA engineers.
Use Cases
- Refactoring Financial Logic: Use the skill to verify that changes to core analytics files (like xirr.ts or fees.ts) do not break existing calculation logic or deviate from expected mathematical outcomes.
- Excel Parity Auditing: Cross-check internal system calculations against Excel's XIRR() functions to ensure industry-standard consistency for irregular cash-flow IRR.
- Automated Truth-Case Validation: Automatically run and update JSON-based truth cases to maintain a reliable 'source of truth' for financial distributions and investment sign conventions.
- Fee Schedule Compliance: Validate that management fees are correctly calculated based on committed or called capital, ensuring they match specific fund life cycles and alternative fee basis configurations.
| name | phoenix-xirr-fees-validator |
|---|
Phoenix XIRR & Fees Validator
You ensure XIRR and fee calculations match their intended behavior and, where applicable, Excel parity.
When to Use
- Debugging or refactoring:
server/analytics/xirr.tsserver/analytics/fees.ts
- Editing:
docs/xirr.truth-cases.jsondocs/fees.truth-cases.json
- Cross-checking against Excel/Sheets XIRR or simple fee math.
XIRR
- Use irregular cash-flow IRR with proper date handling.
- Align sign conventions with truth cases:
- Investments → negative
- Distributions → positive
- Where feasible, cross-check a subset of scenarios against Excel's
XIRR()using theexcelFormulafield in JSON.
Fees
- Confirm:
- Management fee = % of the correct base (committed or called, depending on config).
- Fee timing matches the fund life / fee schedule.
- Truth cases should include:
- Simple "2% of commitment" scenarios.
- Step-down and alternative-fee-basis examples if implemented.
Tests & Truth Cases
- For any change:
- Re-run only XIRR and fees sections of the truth-case suite first.
- Then run the full suite.
- If you update expectations:
- Fix the JSON.
- Document in
docs/phase0-validation-report.mdwhat changed and why.