phoenix-docs-sync
Syncs calculations documentation and JSDoc with actual behavior. Use after non-trivial changes to calculation modules.
When & Why to Use This Skill
Phoenix Docs Sync is a specialized Claude skill designed to maintain perfect alignment between a codebase and its technical documentation. It automates the synchronization of JSDoc comments and Markdown files with the actual behavior of calculation modules, specifically targeting complex logic like XIRR, waterfalls, and fee structures. By ensuring that documentation never contradicts the implementation, it eliminates manual maintenance overhead and prevents technical debt caused by outdated specifications.
Use Cases
- Scenario 1: Automatically updating 'docs/calculations.md' and JSDoc in analytics modules after modifying complex financial logic such as XIRR, waterfalls, or capital allocation to ensure documentation reflects the new behavior.
- Scenario 2: Synchronizing technical phase reports and README files when truth-case semantics change or when precision logic (e.g., Decimal.js) is updated, maintaining a single source of truth.
- Scenario 3: Streamlining the code review process by ensuring that all JSDoc parameters, return types, and semantic descriptions are updated in the same change set as the logic modifications.
| name | phoenix-docs-sync |
|---|
Phoenix Docs Sync
You keep docs and comments aligned with reality for all calculation modules.
When to Use
- After modifying:
- XIRR, waterfall, fees, capital allocation, exit recycling, or reserve logic
- When:
- Truth-case semantics change
- Clawback behavior is clarified or corrected
- Precision / Decimal.js logic changes
Targets
docs/calculations.md- Relevant sections in
README.md - JSDoc in:
server/analytics/*.ts- Shared types for waterfalls, fees, etc.
- Phase reports:
docs/phase0-validation-report.mddocs/phase1a-completion-report.md
Workflow
- Read the updated code and any relevant truth-case JSONs.
- Update documentation to:
- Describe what the module computes in plain English.
- Highlight key assumptions and invariants.
- Reference example truth-case IDs where helpful.
- Update JSDoc:
- Parameters
- Returns
- Semantics (especially around clawback and precision)
- Ensure no documentation mentions outdated semantics (e.g., "hard floor" for clawback when implementation is shortfall-based partial).
Invariants
- Docs must never contradict the actual implementation or truth cases.
- Any semantic change to a calculation should be reflected in docs and JSDoc in the same PR or change set.