StaggeredTripleDifference PR-A: Ortiz-Villavicencio & Sant'Anna (2025) paper review

[igerber]

Summary

• Adds docs/methodology/papers/ortiz-villavicencio-santanna-2025-review.md — the canonical scholarly review of arXiv:2505.09942v3 (Ortiz-Villavicencio & Sant'Anna 2025, Better Understanding Triple Differences Estimators), the shared primary source for the TripleDifference (Complete) and StaggeredTripleDifference (In Progress) estimators.
• Full-paper, equal-depth review version-pinned to arXiv v3: §2 framework + four identifying assumptions (S / SO / NA / DDD-CPT); §3 the "three-not-two-DiDs" covariate result and the not-yet-treated-pooling bias; §4 nonparametric identification (Theorem 4.1 / Eq. 4.5), RA/IPW/DR estimands (Eqs. 4.1–4.4), the optimal-GMM combination across comparison cohorts (Eqs. 4.11–4.12, Remark 4.6 RIF), event-study/overall aggregation (Eqs. 4.13–4.14); influence-function inference (Theorem 4.2, Corollary 4.2); and the three empirical illustrations (§6).
• Pins the ## TripleDifference and ## StaggeredTripleDifference REGISTRY Primary-source citations to arXiv v3 and adds a one-line Paper review on file: cross-reference (matching the Goodman-Bacon / Roth pattern) so the review is not orphaned.

This is wave 1 of a 2-PR methodology promotion for StaggeredTripleDifference (PR-A = paper review only). PR-B will add the paper-equation-anchored Verified Components tests, wire the R triplediff::ddd(panel=TRUE) parity goldens, formalize the documented deviations, and flip the tracker row to Complete.

Methodology references (required if estimator / math changes)

• Method name(s): TripleDifference, StaggeredTripleDifference (DDD)
• Paper / source link(s): Ortiz-Villavicencio, M., & Sant'Anna, P. H. C. (2025). Better Understanding Triple Differences Estimators. arXiv:2505.09942v3 — https://arxiv.org/abs/2505.09942v3
• Any intentional deviations from the source (and why): None introduced. The review documents (does not change) three pre-existing implementation deviations already labelled in REGISTRY.md — comparison-cohort admissibility (R triplediff rule), aggregation-weight population, and per-cohort WIF — flagged for PR-B to formalize. All REGISTRY equation anchors were verified accurate against v3.

Validation

• Tests added/updated: No test changes — paper-review-only PR; methodology tests + R parity land in PR-B.
• Backtest / simulation / notebook evidence (if applicable): N/A (documentation only).
• Local AI review (codex, --backend codex): 6 rounds, ✅ throughout; all actionable findings addressed. The round-6 P2/P3 were verified false positives (the reviewer cross-checked a different arXiv version's remark numbering — Remark 4.7 is correct in v3).

Security / privacy

• Confirm no secrets/PII in this PR: Yes (secret scan clean; the paper PDF is kept outside the repo and is not committed).

---

🤖 Generated with Claude Code

[github-actions]

Overall Assessment

✅ Looks good

Executive Summary

• The PR is documentation-only: it pins the TripleDifference and StaggeredTripleDifference registry entries to arXiv:2505.09942v3 and adds a dedicated paper-review cross-reference in both sections.
• The new review’s high-level paper summary matches the official arXiv abstract: the paper argues that naive covariate-adjusted DDD and pooled not-yet-treated comparisons can be biased, and it develops RA/IPW/DR DDD estimators plus multi-comparison-group inference. (arxiv.org)
• The review’s implementation-note deviations mostly line up with the live registry contract.
• One P3 informational gap remains: the new review calls the Eq. 4.14 overall-aggregation departure an “existing documented deviation,” but the main registry still exposes that point only as plain prose, not under the project’s formal **Note:** / **Deviation ...:** labeling convention.
• No code, performance, security, or testing blockers.

Methodology

• Severity: P3. Impact: docs/methodology/papers/ortiz-villavicencio-santanna-2025-review.md:L236 says the library’s departure from paper Eq. 4.14 is an “existing documented deviation,” but docs/methodology/REGISTRY.md:L2154-L2157 currently states that difference only as unlabeled prose. Since the project’s mitigation convention explicitly keys off labeled **Note:** / **Deviation ...:** blocks, this deviation is readable but not formally machine-recognizable. Concrete fix: either promote the registry sentence to a labeled **Deviation from paper:** or **Note:** block, or soften the new review’s wording to say the difference is “described in REGISTRY” rather than already “documented” under the convention.
• No other methodology findings. The new review’s deviation inventory agrees with the live registry on comparison-cohort admissibility, aggregation-weight population, per-cohort WIF, and deferred analytical clustering at docs/methodology/REGISTRY.md:L2124-L2130, L2165-L2173, and L2206-L2208. The v3 pin itself matches arXiv’s current version history. (arxiv.org)

Code Quality

• No findings. The diff does not modify estimator or inference code paths.

Performance

• No findings. No runtime behavior changes.

Maintainability

• No findings beyond the methodology-labeling issue above. The new registry-to-review cross-links improve discoverability.

Tech Debt

• No new finding. Existing staggered DDD follow-ups remain appropriately tracked in TODO.md:L89-L91 and TODO.md:L209-L210.

Security

• No findings.

Documentation/Tests

• No findings. No test changes are needed for a documentation-only PR, and the new cross-reference reduces the risk of the paper review becoming orphaned.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 3060009fdc2a02d2ce71ec7dd7f3d7806d2a13ce

---

Overall Assessment

✅ Looks good

Executive Summary

• Documentation-only PR: the diff updates the two DDD registry entries and adds a new paper review at docs/methodology/papers/ortiz-villavicencio-santanna-2025-review.md:L1.
• The registry now pins both TripleDifference and StaggeredTripleDifference to arXiv:2505.09942v3; arXiv shows v3 as the latest revision, posted on July 18, 2025. citeturn0view1
• The review’s high-level methodology framing matches the paper’s core claim: naive difference-of-two-DiDs / 3WFE can fail with covariates, pooled not-yet-treated comparisons can bias staggered DDD, and the paper proposes RA/IPW/DR DDD with aggregation across valid comparison cohorts. citeturn0view1
• Re-review result: the prior P3 wording issue is resolved. docs/methodology/papers/ortiz-villavicencio-santanna-2025-review.md:L236 now says the Eq. 4.14 departure is only described in registry prose and formal labeling is deferred, which matches docs/methodology/REGISTRY.md:L2154-L2157.
• No new unmitigated P0/P1/P2/P3 findings in the changed files.

Methodology

• No findings.
• The previous informational gap is resolved by the wording at docs/methodology/papers/ortiz-villavicencio-santanna-2025-review.md:L236 and the existing registry prose at docs/methodology/REGISTRY.md:L2154-L2157. This PR no longer overstates the registry’s formal deviation-label status.

Code Quality

• No findings. No estimator or inference code changed.

Performance

• No findings. No runtime behavior changed.

Maintainability

• No findings.
• The new registry-to-review cross-links at docs/methodology/REGISTRY.md:L1954 and docs/methodology/REGISTRY.md:L2064 improve discoverability.

Tech Debt

• No findings.
• Existing staggered DDD follow-ups remain tracked in TODO.md:L89-L91; this PR does not add new deferred work.

Security

• No findings.

Documentation/Tests

• No findings.
• No test updates are required for a documentation-only PR.