Tax-Loss Harvesting Test-Case Design Worksheet
A TLH engine that ships without exercising every wash-sale variant is a TLH engine that ships with a footnote. This worksheet enumerates the structural cases — cross-account wash sales, lot-selection method by account type, short-vs-long-term boundary cases — and outputs the named synthetic households that exercise each. Pairs with the TLH Simulator dataset.
What you walk away with
~16 min · 5 sections · 6 fields- An enumerated test case list covering wash-sale, lot-selection, cross-account, and term-boundary structures.
- A documented expected disposition per case — what the engine should do, with the IRS reference.
- An identified archetype set that exercises each case in the TLH Simulator pack.
- A coverage check that surfaces structurally tricky cases the team forgot to design for.
Engine scope
Wash-sale cases
Per IRC 1091 — a wash sale occurs if the taxpayer (or related party) acquires substantially identical securities within 30 days before or after the loss-realization date.
Specifics: ticker, dates, amounts, account ownership.
What the engine should compute and disclose.
Specifics: ticker, dates, amounts, account ownership.
What the engine should compute and disclose.
Specifics: ticker, dates, amounts, account ownership.
What the engine should compute and disclose.
Specifics: ticker, dates, amounts, account ownership.
What the engine should compute and disclose.
Lot-selection cases
Lots, dates, basis, sale amount. Show the term-boundary if any.
Lots, dates, basis, sale amount. Show the term-boundary if any.
Lots, dates, basis, sale amount. Show the term-boundary if any.
Short-vs-long-term boundary cases
Coverage roll-up
Aggregate coverage index: wash-sale (50%) + lot-selection (30%) + term-boundary (20%). Below 50% indicates structural gaps.
Next steps
Map the populated cases to the TLH Simulator pack archetypes; each test case should resolve to a named archetype the engine can run against. The Edge-Case Coverage Score scores the result.
Key takeaways
- Cross-account wash sales are the most under-tested area. Spouse-IRA repurchases catch most teams off-guard.
- Substantially-identical determination is engine-specific. Document the firm's policy explicitly per case.
- Term-boundary cases are mechanical. If the engine has a 365-day case, it should also have a 364 and a 366 — three rows.
- The status column is a release gate. Cases with status < 'verified in CI' should not ship to production.
FAQ
Why distinguish cross-account from single-account wash sales?
IRC 1091 applies regardless of which account the repurchase happens in — including IRAs and spouse accounts. Most TLH bugs surface in the cross-account case because the engine wasn't designed to look across accounts.
What about 'substantially identical' edge cases?
There's no IRS bright-line. The firm's policy must define it (e.g. SPY → IVV is a wash; SPY → VTI is not). The worksheet captures the cases that test the policy boundary.