Phoenix Precision Guard

Phoenix Precision Guard

You enforce numeric precision and type safety for all P0 calculation paths in the Phoenix VC fund model.

When to Use

Invoke this skill when:

• Removing or triaging parseFloat in calculation code
• Tightening ESLint or TypeScript strictness for analytics modules
• Configuring or validating Decimal.js usage
• Adding or updating precision tests
• Investigating numeric drift or rounding errors in calculations

Do not use this skill for:

• Waterfall semantic changes (use phoenix-waterfall-ledger-semantics)
• Truth-case orchestration (use phoenix-truth-case-orchestrator)
• XIRR or fee logic bugs (use phoenix-xirr-fees-validator)
• Probabilistic/Monte Carlo work (use phoenix-advanced-forecasting)

Scope

P0 calculation files include (non-exhaustive):

• server/analytics/xirr.ts
• server/analytics/waterfall-*.ts
• server/analytics/fees.ts
• server/analytics/capital-allocation.ts
• server/analytics/exit-recycling.ts
• server/utils/financial.ts
• client/src/core/engines/*.ts

ESLint & TS Rules

ESLint

• Ban parseFloat in P0 paths.
• Require explicit radix for parseInt.
• Disallow implicit type coercion in calculation code (except !! as needed).

Run:

/fix-auto
# or
npm run lint

TypeScript Strictness

Incrementally enable:

• noImplicitAny
• strictNullChecks
• strictFunctionTypes
• noImplicitReturns

For each flag:

1. Enable in tsconfig.json.
2. Run npm run check.
3. Fix errors in P0 calculation files first.
4. Baseline non-P0 issues with @ts-expect-error and a comment referencing the phase.

parseFloat Triage

1. Find all occurrences:

   rg "parseFloat" server/analytics/ client/src/core/engines/
   

2. Classify each usage:

   • Calculation → replace with Decimal.js (new Decimal(value) or Decimal(value)).
   • Config/ENV integer → parseInt(value, 10).
   • Non-critical/test → deprioritize.

3. After each batch of replacements:

   • Run the truth-case suite.
   • Confirm no regression in pass rate.

Decimal.js Precision

• Ensure a single central configuration (e.g., in a shared utility) sets precision, e.g.:

  Decimal.set({ precision: 20 });
  

• Add a dedicated precision test file (e.g., tests/unit/precision.test.ts) asserting behavior like:

  • 0.1 + 0.2 = 0.3
  • Long chains of operations remain stable.

Invariants

• Truth-case pass rates must remain ≥ baseline after precision refactors.
• No new P0 calculation path should use native number math where precision matters.
• TypeScript and ESLint errors in P0 files must be fixed, not silenced.