[igerber]

Summary

• 4.0 cut, PR 4c-ii-b: the docs/benchmarks half of the MultiPeriodDiD removal, now based on main after PR 4c-ii-a (feat(v4): PR 4c-ii-a of the 4.0 cut - remove MultiPeriodDiD, MultiPeriodDiDResults, PeriodEffect and EventStudy #870) merged. Supersedes docs(v4): PR 4c-ii-b of the 4.0 cut - methodology/benchmark prose, tracking rows and the oracle fixture's mpd_twin prune #871, which GitHub auto-closed when feat(v4): PR 4c-ii-a of the 4.0 cut - remove MultiPeriodDiD, MultiPeriodDiDResults, PeriodEffect and EventStudy #870's branch was deleted and would not reopen after the rebase; same single commit, same 23 files, rebased onto the feat(v4): PR 4c-ii-a of the 4.0 cut - remove MultiPeriodDiD, MultiPeriodDiDResults, PeriodEffect and EventStudy #870 merge commit. Item 4c-ii was split because the single diff exceeded the AI review input budget; nothing here is needed by a CI gate or the REGISTRY deviation rule in the same diff as the source, which is why it could be deferred.
• Methodology / tracking prose: docs/methodology/REGISTRY.md (the remaining historical mentions outside the archive note and the two Notes that shipped in feat(v4): PR 4c-ii-a of the 4.0 cut - remove MultiPeriodDiD, MultiPeriodDiDResults, PeriodEffect and EventStudy #870), REPORTING.md, survey-theory.md, variance-conventions.md (one prose line; the generated table is unchanged from feat(v4): PR 4c-ii-a of the 4.0 cut - remove MultiPeriodDiD, MultiPeriodDiDResults, PeriodEffect and EventStudy #870), METHODOLOGY_REVIEW.md, docs/benchmarks.rst (prose names the live TWFE event-study arm; the committed 2026-07 refresh tables stay byte-identical with a provenance sentence), docs/survey-roadmap.md, docs/performance-plan.md, CONTRIBUTING.md, the repo debugging-notes file, the Rust rank-deficiency comment. TODO rows 33/35/38/95/99 reworded (the 4c-ii-a rows 89 and the two new rows are unchanged); three DEFERRED rows that governed the removed class are retired.
• Benchmarks (user decision 2026-10-25: relabel + local parity run only): the live event-study arm is the NEW benchmarks/python/benchmark_twfe_event_study.py (TwoWayFixedEffects(cluster=unit).fit(..., event_study=True, spec="within"), same CLI and output keys as the frozen script; period_effects converted to reference-relative event_time as before; the headline is the post-period average with the former container's exact arithmetic). benchmarks/run_benchmarks.py calls it. benchmark_multiperiod.py and benchmarks/refresh_2026_07/ stay frozen (header comment): that harness runs the script inside pinned 3.5.3/3.7.0 venvs that predate event_study=True. speed_review/bench_brand_awareness_survey.py relabels to spec="pooled" (the 3.x call passed unit= to a class that read it only for Conley, so the measured design was the pooled one); benchmark_honest.py drops the fake per-period record type; the two R scripts update comments only.
• Oracle fixture: tests/fixtures/v4_twfe_event_study_oracles.json drops its mpd_twin records and the mpd_ctor/mpd_fit echo keys (every twfe record and the provenance block byte-identical; pruned through the capture script's own dump_fixture serializer); tests/helpers/twfe_es_oracle_lanes.py loses the MPD twin fields; tests/_capture_v4_merge_mpd_oracles.py is TWFE-only and documents that a re-run is a re-baseline (the independent twin is gone); tests/fixtures/README.md records the per-lane capture SHAs (68e383b; d45d531 for the two clustered hc2_bm lanes).

Methodology references (required if estimator / math changes)

• Method name(s): N/A - prose, tracking files and benchmark scripts only; no diff_diff/ change.
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: no test logic changes; the oracle fixture prune and the lane-metadata cleanup are pinned by tests/test_twfe_event_study_decoupling.py (31 passed on python and rust). Gates on this branch: naming guard (docs lane), tracking files, variance-conventions table gate, changelog fragments, docs IA, doc snippets, guides, doc-deps, the review-script section map, the ledger matrix: 1354 passed.
• Backtest / simulation / notebook evidence (if applicable): local R parity run of the new arm (run_benchmarks.py --estimator multiperiod --scale small, R + fixest 0.14.2): Python vs R headline ATT differ by 2e-12, SE relative difference 0.0%, per-period effects correlation 1.000 (max att diff 3e-11), compare_estimates PASS; the p-value/CI differ as before because R uses nobs - k while the surface uses its shared post-row df (not gated).

Security / privacy

• Confirm no secrets/PII in this PR: Yes

Changelog

• changelog.d/ fragment added (or N/A - no user-visible change): Yes - changelog.d/20261025-v4-pr4c-ii-b-docs-benchmarks.md (### Internal)

Follow-ups

• Cut sequence continues with item 5 (storage flip) once this PR lands.

[igerber]

Supersedes #871 (auto-closed when #870's branch was deleted; could not be reopened after the rebase onto main).

[github-actions]

Overall assessment

✅ Looks good — no unmitigated P0/P1 findings identified.

Executive summary

• The new TWFE benchmark preserves the intended unit-FE design and covariance-aware post-period average.
• Empty post-period selections raise; undefined SEs produce NaN inference through safe_inference().
• All 13 retained TWFE oracle records and provenance are unchanged.
• A changelog fragment is present.
• Static checks passed. Numerical tests and direct paper retrieval were unavailable in this environment.

Methodology

No new methodology defects identified. The within/pooled specifications and averaging formula agree with the registry and implementation docstrings (benchmarks/python/benchmark_twfe_event_study.py:L137-L163; docs/methodology/REGISTRY.md:L250-L282).

• P3 — Informational: documented inference convention.
  Impact: Python and R can report different p-values/CIs because their degrees of freedom differ. The registry explicitly documents this convention (docs/methodology/REGISTRY.md:L593-L617).
  Concrete fix: None required.

Source review included the registry, docstrings, committed R specification, and local Rambachan–Roth/Roth paper reviews. Direct access to the cited NBER paper failed because network DNS was unavailable.

Code Quality

No findings. The new averaging code retains cross-period covariances using np.ix_ and delegates inference to the shared helper.

Performance

No findings in the changed code. Historical benchmark tables retain explicit provenance.

Maintainability

No findings. Removed lane fields have been removed from their callers and fixture metadata consistently.

Tech Debt

• P3 — Informational: independent R regression fixture remains tracked.
  Impact: Historical self-captures protect against numerical drift but cannot detect defects predating capture (TODO.md:L97).
  Concrete fix: No action required for this PR; the tracked follow-up specifies committed fixest goldens for both specifications, including unbalanced and covariate panels.

Security

No findings in the changed files.

Documentation/Tests

No release-note finding: the PR includes a changelog.d/ fragment.

Verification completed:

• Parsed all six changed Python files successfully.
• Reconstructed the previous fixture from the supplied diff and verified that only MPD records/echo keys were removed.

Numerical verification could not run: NumPy, pandas, SciPy, pytest, and Rscript are unavailable. The PR’s reported numerical validation was therefore not independently reproduced.