shift-share-diagnostics
Diagnostics for shift-share and exposure-weighted designs, including designs the paper does not label shift-share: Rotemberg-weight concentration, effective number of shocks, decomposition identity, placebo-shock rejection, and shock-level inference. Invoke from `code-and-data` whenever any regressor or instrument is an exposure-weighted sum of shocks.
isitcredible · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add isitcredible/research_skills --skill shift-share-diagnosticsAbout this skill
name: shift-share-diagnostics
description: >-
Diagnostics for shift-share and exposure-weighted designs, including
designs the paper does not label shift-share: Rotemberg-weight
concentration, effective number of shocks, decomposition identity,
placebo-shock rejection, and shock-level inference. Invoke from
code-and-data whenever any regressor or instrument is an
exposure-weighted sum of shocks.
Shift-share diagnostics
Answer the shock-level question with shock-level tools. The trigger is structural, not nominal: ANY regressor or instrument built as an exposure-weighted sum of shocks is a latent shift-share design, whether or not the paper uses the words — and a paper can pass every unit-exclusion and clustering check while its identification rests on two shocks, which only the shock-level diagnostics can reveal.
NOT_APPLICABLE when no target regressor has the exposure-weighted-sum
structure — record that the structure was checked for, since the unlabelled
case is the one that escapes.
The source-audited cribs behind this module:
../../references/methods/shift_share/gpss_2020_bartik_instrument.md
(Rotemberg weights, the decomposition identity, shares-vs-shocks framing),
../../references/methods/shift_share/bhj_2022_quasi_experimental_ssiv.md (shock
exogeneity, incomplete shares, the Col 1→2→3 walk),
../../references/methods/shift_share/akm_2019_shift_share_inference.md (AKM/AKM0
shock-level inference and its validity conditions), and
../../references/methods/shift_share/borusyak_hull_2020_nonrandom_exposure.md
(non-random exposure and recentering).
The textbook-level overview of the whole program is Borusyak, Hull &
Jaravel (2025), "A Practical Guide to Shift-Share Instruments," Journal
of Economic Perspectives 39(1): 181–204; cribbed at
../../references/methods/shift_share/bhj_2025_practical_guide.md —
its two checklist columns (shifts margin / shares margin) supply the
tailored-shares, share-vintage, and combination-sensitivity checks
below.
Core checks
- Rotemberg-weight concentration, computed on the exact estimation sample — not the full dataset, and not the sample of a different column. Which shocks carry the estimate, and how concentrated are the weights?
- Effective number of shocks. The inverse Herfindahl of the shocks' average exposure weights, 1/Σ_k s̄_k² (BHJ 2022 Table 1; BHJ 2025) — not of the Rotemberg weights: an estimate with thousands of nominal shocks and an effective number under ten is identified off a handful of comparisons.
- Decomposition identity verified on the estimation file. Confirm the weighted combination of just-identified estimates reproduces the reported coefficient; a failure means the sample, weights, or specification differ from what the decomposition assumes.
- Adjudicate the identifying margin — and route the verdict through it. What varies across units, what varies across shocks: then state, with the reason, which margin the design's strongest defense claims as exogenous — the shares (the exposure geography or settlement pattern, the Goldsmith-Pinkham / Card reading) or the shocks (the aggregate shifters, the BHJ reading). This is a judgment the report must defend, not a default: an enclave/origin-share instrument is defended on shares, a lottery-style shifter on shocks. The margin decides which tests are verdict-bearing. Share exogeneity is falsified by share-level evidence — location-level balance, and negative controls / pre-trends of the outcome on the exposure geography (an instrument that predicts the pre-period outcome fails share exogeneity directly). The shock margin fails on shock-level balance (exogeneity) or on few effective shocks (the many-shocks law of large numbers); concentration does not falsify exogeneity, it breaks the many-shocks condition — and shock-level SEs are themselves unreliable when the effective number of shocks is small, so report it as a limit. Results on the other margin rebut only what the paper itself claims — run them when the paper claims them (a shock-level placebo is a shock-level claim on the paper), but label them rebuttals, never "the diagnostic this design calls for". When the margin is genuinely arguable the headline must not silently rest on one choice; when both margins fail, say so in both directions — "the shares are not exogenous AND the shocks are few and concentrated" is strictly stronger than a verdict that routes through one contested margin.
- Construction algebra before test selection. Derive the instrument's residualised form under the actual FE/control structure. After unit and period effects are partialled out, an exposure-weighted instrument often reduces to a mechanical function of observables (products or deviations of unit size and shock aggregates) whose loading on predetermineds is algebraic, not coincidence — a share built from predicted origins can be, after partialling, a unit-size measure times a shock deviation. Write the algebra down in the module report: it tells you which balance tests are actually binding and which the construction guarantees will fail.
- Share vintage and tailoring (BHJ 2025). Fixed-at-baseline and time-updated shares are different instruments answering different assumptions — updated shares can reimport the endogeneity the instrument exists to escape (shocks moving shares after the experiment starts). A lagged-share construction helps only if it cuts cov(share, ε) by more than it cuts cov(share, x); demand that argument, not the mere fact of lagging. On the shares margin, check tailoring: shares measuring general exposure to many shock types (industrial composition, generic pull factors) are a non-starter — share exogeneity needs shares tailored to the shocks that move this treatment.
- Placebo-shock rejection: centring AND rejection rates. Replace the shocks with permuted or