docs(methodology): add LP-DiD (Dube et al. 2025) paper review and registry entry

[igerber]

Summary

• Phase A (paper-review, docs only) for the LPDiD estimator initiative.
• Add docs/methodology/papers/dube-2025-review.md — structured review of Dube, Girardi, Jordà & Taylor (2025), incorporating the official online appendix (FWL weight derivations, covariate-weight positivity conditions, non-absorbing weights).
• Add ## LPDiD methodology section + TOC entry to docs/methodology/REGISTRY.md.
• Add a "Local Projections DiD" section to docs/references.rst (Dube et al. 2025; Jordà 2005).

Methodology references (required if estimator / math changes)

• Method name(s): LPDiD — Local Projections Difference-in-Differences.
• Paper / source link(s): Dube, A., Girardi, D., Jordà, Ò., & Taylor, A. M. (2025). "A Local Projections Approach to Difference-in-Differences." Journal of Applied Econometrics, 40(5), 741-758. https://doi.org/10.1002/jae.70000 (Open Access; NBER WP 31184). Reference implementations: Stata lpdid (SSC s459273), R alexCardazzi/lpdid.
• Any intentional deviations from the source (and why): None in this PR (documentation only). Two items recorded in the registry for the source PR (Phase B): (1) the paper specifies no SE formula, so cluster-robust-at-unit is an implementation choice validated against the reference package, not the paper; (2) direct covariate inclusion requires a homogeneous-covariate-effects assumption per online appendix B.2.2 — the regression-adjustment path is preferred.

Validation

• Tests added/updated: None (documentation only). Verified locally: tests/test_doc_deps_integrity.py green (152 passed), references.rst RST section underline valid, REGISTRY TOC/section structure intact.
• Backtest / simulation / notebook evidence (if applicable): N/A.
• Scope note: doc-deps.yaml and the llms.txt catalog entry are intentionally deferred to the source PR (Phase B) — test_doc_deps_integrity requires the mapped source file to exist on disk, and the llms catalog is coupled to __all__.

Security / privacy

• Confirm no secrets/PII in this PR: Yes (the source paper PDF is gitignored and not committed).

---

🤖 Generated with Claude Code

[github-actions]

Overall Assessment
⚠️ Needs changes

Executive Summary

• Highest unmitigated issue: P1 methodology documentation mismatch in the stated LP-DiD parallel-trends assumption.
• Most other LP-DiD contract material aligns with the accessible source: binary absorbing setup, clean-control sample, variance weights, equal-weight WLS/RA routes, PMD/pooling/composition notes, and the SE caveat. (nber.org)
• No estimator code, inference code, defaults, or public API changed in this PR.
• git diff --check passed. I could not run tests/test_doc_deps_integrity.py because pytest is not installed in this environment.

Methodology

• Severity: P1
  Impact: docs/methodology/REGISTRY.md:L1797-L1799 and docs/methodology/papers/dube-2025-review.md:L21-L22 restate Assumption 2 as a one-period first-difference condition using y_{i,t-1} and call it weaker. The source’s formal Assumption 2 is stated relative to the first period, y_it(0) - y_i1(0), for all t and cohorts; the “first-lag weaker than PMD” point belongs to the PMD/base-period discussion, not the formal identification assumption. (nber.org)
  Concrete fix: Replace the Assumption 2 formula in both files with the source version using y_i1(0). If you want to keep the adjacent-difference interpretation, add a separate note saying it is an equivalent restatement only when imposed over all adjacent periods, and keep the “weaker” claim scoped to first-lag vs PMD under partial-PT deviations.

• Severity: P3
  Impact: docs/methodology/REGISTRY.md:L1820-L1822 says reweight=True weights each “clean-control obs,” which can be read as only control observations. The source weighting applies to each observation belonging to CCS_{g,h}; that sample includes newly treated observations and their clean controls. (nber.org)
  Concrete fix: Reword to “weight each observation in the clean-control sample CCS_{g,h} (newly treated and clean controls) by ...”.

Code Quality
No findings. The PR is documentation-only.

Performance
No findings. No runtime path changed.

Maintainability

• Severity: P3
  Impact: docs/methodology/papers/dube-2025-review.md:L10-L12 still reads like a staging/template instruction (“Copy the ## LPDiD section...”) even though the registry entry is already added.
  Concrete fix: Rephrase as “The corresponding registry entry is mirrored in docs/methodology/REGISTRY.md.”

Tech Debt
No blocking findings. The Phase-B implementation, doc-deps, llms catalog, non-absorbing, and survey items are explicitly tracked in docs/methodology/REGISTRY.md:L1840-L1855, so they are P3/informational under the project’s deferred-work policy.

Security
No findings. I saw no secrets or PII in the changed docs.

Documentation/Tests
No P1 documentation/test gaps beyond the methodology mismatch above. Verification note: git diff --check passed; python -m pytest tests/test_doc_deps_integrity.py -q -p no:cacheprovider could not run because pytest is unavailable.

Path To Approval

1. Update Assumption 2 in docs/methodology/REGISTRY.md:L1797-L1799 and docs/methodology/papers/dube-2025-review.md:L21-L22 to match the source’s y_it(0) - y_i1(0) statement.
2. Move or qualify the “weaker first-lag PT” language so it clearly refers to the PMD/base-period tradeoff, not the formal LP-DiD identification assumption.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 4345f0f29955945c6920eb13e7938bb455edd087

---

Overall Assessment

✅ Looks good

Executive Summary

• Prior P1 is resolved: LP-DiD Assumption 2 now uses the period-1 untreated-outcome trend statement in both REGISTRY.md and the paper review.
• The first-lag vs PMD “weaker PT” language is now scoped as a base-period robustness/efficiency issue, not the formal identification assumption.
• No estimator code, variance code, inference code, defaults, or public API changed.
• Deferred Phase-B items are explicitly tracked in the LPDiD implementation checklist.
• git diff --check passed; local pytest execution could not run because pytest is not installed.

Methodology
No unmitigated findings.

Reviewed docs/methodology/REGISTRY.md:L1795-L1836 and docs/methodology/papers/dube-2025-review.md:L20-L108. The LPDiD documentation now captures the key contract: no anticipation, period-1 parallel trends, absorbing binary main path, clean-control restriction, non-negative variance weights, reweighted/RA equal-weight routes, covariate positivity caveat, SE non-specification, PMD, composition, and non-absorbing deferral.

Code Quality
No findings. Documentation-only PR.

Performance
No findings. No runtime path changed.

Maintainability
No findings. The earlier staging/template wording in docs/methodology/papers/dube-2025-review.md:L10-L12 has been cleaned up.

Tech Debt

• Severity: P3 informational
  Impact: Phase-B source wiring, doc-deps.yaml, llms.txt, SE convention documentation, non-absorbing support, and survey support are deferred, but this is explicitly tracked in docs/methodology/REGISTRY.md:L1840-L1855.
  Concrete fix: No action required for this docs-only PR; complete these checklist items when the LPDiD implementation lands.

Security
No findings. I saw no secrets or PII in the changed docs.

Documentation/Tests
No blocking findings.

Verification:

• git diff --check passed.
• python -m pytest tests/test_doc_deps_integrity.py -q -p no:cacheprovider could not run: /usr/bin/python: No module named pytest.
• The doc-deps integrity test only enforces mappings for existing public diff_diff/*.py modules, so deferring diff_diff/lpdid.py mapping is compatible with this docs-only phase.