Evaluate "Report (Beta) — Overview & Tax Optimization" feature

[jamespepper81]

Summary

Goal: Verify whether the current "Report (Beta) Overview / Tax Optimization" feature provides accurate, actionable capital gains information and usable guidance for users to optimize tax outcomes. Produce a prioritized list of improvements (accuracy fixes, UX, exports, and documentation) and a plan to implement them.

Scope

• Validate capital gains calculations across common cost-basis methods (FIFO, LIFO, HIFO, Specific Identification) and the default method used by the feature.
• Confirm correct handling of:
  • Partial spends and UTXO selection implications
  • Transaction fees and their attribution to cost basis
  • Chain reorganizations, coin splits, and merges
  • Transfers between user-controlled addresses (non-taxable internal moves)
  • Incoming/outgoing swaps and token trades (onchain DEX trades)
  • Stablecoins and cross-currency flows
  • Timestamp and timezone handling for tax-year boundaries
• Evaluate UX: clarity of results, explanations, exportability (CSV/PDF), and configuration options (tax year, cost-basis method).
• Evaluate legal/disclaimer text and jurisdiction sensitivity (not tax advice).

Deliverables

• Report summarizing findings: correctness gaps, edge cases, and recommended fixes.
• Concrete improvement list with effort estimates and prioritization (High / Medium / Low).
• Example test cases and example wallets demonstrating current miscalculations (if any).
• Suggested UI changes, copy edits, and export formats for tax accountants and end users.
• A small set of unit/integration tests (or test vectors) to prevent regressions.

Acceptance Criteria

• Reproduce calculations for at least 3 representative wallets (simple buys/sells, mixed onchain swaps, internal transfers).
• Demonstrate correct capital gains numbers for each under at least two cost-basis methods (e.g., FIFO and HIFO) or document why not supported.
• Provide reproducible test vectors (txids + expected cost basis/gain numbers) and automated tests where feasible.
• UX suggestions include at minimum: an explanation of methodology, a toggle for cost-basis method, and CSV/PDF export of transactions/gains.
• Documentation/disclaimer updated to avoid implying tax advice; recommend consulting a tax professional.

Proposed Task Breakdown

1. Investigation (2–4 days)
   • Inventory existing implementation: where cost-basis computations run; what assumptions are encoded.
   • Create representative test wallets (with tx history) to validate current outputs.
2. Accuracy fixes & edge cases (variable)
   • Fix fee attribution, internal transfer detection, and timestamp boundaries if incorrect.
   • Add at least one alternate cost-basis method (if currently single-method) or clearly expose the method used.
3. UX & Exports (1–3 days)
   • Add explicit "Methodology" section in Report UI, explaining assumptions.
   • Add controls: tax year/date-range, cost-basis method selector, and “mark transfer as internal”.
   • Add CSV and PDF export with detailed data: transactions, cost basis, realized/unrealized gains.
4. Testing & CI (1–2 days)
   • Add unit tests with test vectors.
   • Add integration test verifying exported CSV contents match displayed numbers.
5. Documentation & Legal (half-day)
   • Add clear non-advisory disclaimer recommending professional advice for specifics.
6. Optional: Jurisdiction templates (future)
   • Export templates (US 8949, UK SA108 etc.) as follow-ups if demand exists.

UX / Copy Suggestions

• Headline: "Report (Beta) — Overview & Tax Optimization"
• Short summary: "Estimates realized gains and tax-relevant activity. This is an estimate — consult a tax professional."
• Add an “Explain this number” modal that shows how a specific gain was computed.
• Show coverage metric: % transactions reconciled vs. imported external data.
• Clear export button and “Download detailed transactions” option.

Questions / Open decisions

• Which cost-basis methods do we want to support initially? (Minimum: FIFO; desirable: HIFO/Specific ID)
• Do we have or want exchange data integrations to reconcile on-exchange trades?
• What jurisdiction(s) do we prioritize for export templates?
• Do we want a user-facing toggle to mark internal transfers as non-taxable?

Suggested Labels

• enhancement (existing)
• investigation
• tax
• ux
• high-priority (if user-facing in next release)

Suggested Assignees

• jamespepper81 (current)
• Add backend engineer and product/UX reviewer once prioritized.

Estimated Effort

MVP fixes + export: ~1–2 sprints (2–4 weeks) depending on scope of cost-basis support/edge-case handling.

Next Steps

• Confirm cost-basis methods to support and if you want follow-up issues for alternate cost-basis, export, test vectors.
• If so, please list them and they will be created as needed.