heurist-finance: Skill for Claude Code

Pairs & Relative Value

Shared plumbing and output contract: ../_shared/analyst-core.md. A pair converts a market-direction bet into a relationship bet. That removes beta and adds two new ways to lose: the relationship breaks, or it mean-reverts slower than the capital can wait. Both are testable before entry — so test them.

Qualify the pair (compute, don't assert)

Pull both legs: hf_tool.py prices A B --period 3y --out FILE, then a Python block for the statistics. The gates, in order:

1. Economic linkage first. Same demand driver, same input costs, or substitute products — stated in one sentence. Data-mined pairs with no economic reason are the ones that break. (KO/PEP yes; "these two cointegrated in-sample" no.)
2. Cointegration, not correlation. Correlation 0.9 says they wiggle together; cointegration says the spread is stationary — only the second supports mean-reversion trading. Engle–Granger on log prices (regress, ADF-test the residual) over a ~3y lookback, demand p < 0.05 — and require sub-sample stability: re-run on each half of the window and the most recent year; a pair that only cointegrates over the full window is regime-dependent, treat it as failed. High correlation with failed cointegration = trending spread = the classic slow bleed. Failed cointegration with a real economic link and a directional relative view downgrades to the fallback structure: a return-beta-hedged overlay (hedge ratio from a return regression), traded as directional relative value on a thesis falsifier — no bands, no mean-reversion logic, and say it's not a pair.
3. Half-life of the spread (fit OU / AR(1) on the residual: half-life = −ln(2)/ln(φ)). Reject > ~30 trading days — beyond that, capital lock-up and break risk dominate the convergence P&L, and it exceeds the user's multi-week horizon anyway. 5–20 days is the sweet spot.
4. Hedge ratio from the cointegrating regression (not 1:1 shares, not equal dollars unless β≈1): position legs so the traded unit is the stationary spread. Then check residual beta — sector-neutral pairing (both legs same sector) removes ~60% of market beta by construction; cross-sector "pairs" are usually a hidden factor bet (long tech / short energy is a rates trade wearing a pairs costume — say so).
5. Short-leg reality check: borrow availability and fee (equity_overview, short-interest context via equity_screen screen_name=most_shorted_stocks). A pair whose short leg is > 10–15% borrow fee or squeeze-listed has asymmetric blow-up risk — the short leg gets recalled precisely when it's ripping.