docs: HAD ecosystem completion (RTD audit Batch A)

[igerber]

Summary

Closes the gaps left after PR #372 added HeterogeneousAdoptionDiD to the canonical surfaces. The narrative pages did not yet mention HAD, and the 12-symbol HAD pretest suite shipped in had_pretests.py was absent from the API page. Also refreshes the inference-contract block to use the survey_design= canonical kwarg consolidated in PR #376.

• docs/api/had.rst — new HAD Pretests section covering all 12 public symbols (4 single-period tests + 4 result classes + 3 joint tests + 1 joint result), split into aggregate="overall" and aggregate="event_study" subsections matching the workflow's dispatch. Refreshes the inference-contract block to reference survey_design=make_pweight_design(weights) (pweight shortcut) and survey_design=SurveyDesign(...) (full TSL); notes survey= / weights= are deprecated aliases.
• docs/choosing_estimator.rst — HAD entries in all 3 tables (Quick Reference, Standard Error Methods, Survey Design Support) plus a new "Universal Rollout / No Untreated Control" subsection in Detailed Guidance. SE Methods row uses survey_design= canonical naming.
• docs/r_comparison.rst — HAD row in Feature Comparison Table, new "No-Untreated Designs (no R parallel)" subsection, Migration Tips bullet.
• docs/troubleshooting.rst — new HAD Issues section with 4 subsections (estimand resolution / mass-point fallback / classical SE under survey_design= / panel-only event-study).
• docs/practitioner_decision_tree.rst — Start Here option 7, At a Glance row, new "Universal Rollout" section with _section-no-untreated anchor.
• docs/references.rst — Binder citation references the canonical survey_design= paths.
• docs/doc-deps.yaml — extends had_pretests.py entry with llms.txt user-guide dep; adds new top-level local_linear.py entry.

Methodology references (required if estimator / math changes)

• N/A - no methodology changes (docs-only PR; no source files modified).

Validation

• Tests added/updated: No test changes (docs-only).
• Sphinx build: succeeds (python -m sphinx -b html -q docs docs/_build/html); 0 new warnings from this PR (71 pre-existing in bacon.py / staggered_bootstrap.py autosummary unaffected).
• Public API regression: all 12 HAD pretest symbols importable (HADPretestReport, qug_test, stute_test, yatchew_hr_test, did_had_pretest_workflow, QUGTestResults, StuteTestResults, YatchewTestResults, stute_joint_pretest, joint_pretrends_test, joint_homogeneity_test, StuteJointResult); make_pweight_design + SurveyDesign importable.
• Rendered HTML coverage: api/had.html 276 hits, narrative pages 4-8 hits each.
• Cross-reference resolution: _section-no-untreated anchor (definition + cross-ref).
• Style: 0 em dashes in diff.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

[github-actions]

Overall Assessment

⚠️ Needs changes — I found two unmitigated P1 issues on the newly documented HAD public surface.

Executive Summary

• The new HAD Pretests API section itself looks aligned with the exported 12-symbol source surface.
• P1: the PR rewrites the HAD estimator’s pweight/SE contract around survey_design=make_pweight_design(weights), but HeterogeneousAdoptionDiD.fit() explicitly rejects that object and still uses deprecated weights= for the pweight shortcut.
• P1: several new HAD snippets are not runnable because they use nonexistent kwargs/results attributes (outcome, unit, time, dose, results.coef, results.fit_path) instead of the actual HAD API.
• P2: the new R-comparison text is stale as of April 26, 2026; R now has HAD-oriented package entry points, so “no R parallel” is too strong. (cran.r-universe.dev)

Methodology

1. Severity: P1. Impact: affected method is HeterogeneousAdoptionDiD’s weighting/variance contract. docs/api/had.rst:L49-L60, docs/api/had.rst:L67-L70, docs/choosing_estimator.rst:L665-L667, and docs/troubleshooting.rst:L535-L540 now document survey_design=make_pweight_design(weights) as the estimator-side pweight route. That does not match the implementation or the Methodology Registry: data-in HAD surfaces take survey_design=SurveyDesign(...), the deprecated weights= path is still the pweight shortcut, and make_pweight_design(...) is reserved for array-in pretests. Worse, the in-code deprecation text says weights= and survey_design=SurveyDesign(...) currently produce different SE families on HeterogeneousAdoptionDiD.fit(), so the rewritten docs also blur a real variance-family distinction. Cross-check: docs/methodology/REGISTRY.md:L2352-L2353, diff_diff/had.py:L2853-L2891, diff_diff/had.py:L2946-L2967, diff_diff/survey.py:L681-L697, diff_diff/survey.py:L798-L808. Concrete fix: restore the estimator docs to the implemented contract: weights= remains the deprecated pweight shortcut on fit(), survey_design=SurveyDesign(weights='col_name', ...) is the data-in survey route, and make_pweight_design() should only be documented on array-in pretest helpers.

Code Quality

No findings in the changed files.

Performance

No findings in the changed files.

Maintainability

No findings in the changed files.

Tech Debt

No findings. I also did not see any changed-file issue that is already mitigated by TODO.md.

Security

No findings.

Documentation/Tests

1. Severity: P1. Impact: the new HAD examples are not runnable as written. The added snippets call did_had_pretest_workflow(..., outcome=..., unit=..., time=..., dose=...) and HeterogeneousAdoptionDiD.fit(..., outcome=..., unit=..., time=..., dose=...), but the actual signatures are outcome_col, dose_col, time_col, unit_col (diff_diff/had_pretests.py:L4015-L4030, diff_diff/had.py:L2786-L2804). They also print results.coef and results.fit_path, while the HAD result objects expose att and design (diff_diff/had.py:L315-L339, diff_diff/had.py:L667-L690). Affected docs: docs/choosing_estimator.rst:L393-L405, docs/practitioner_decision_tree.rst:L285-L299, docs/r_comparison.rst:L234-L238, docs/troubleshooting.rst:L500-L526. Concrete fix: update all new HAD snippets to use the real kwarg names and result attributes (outcome_col, dose_col, time_col, unit_col, results.att, results.design).

2. Severity: P2. Impact: docs/r_comparison.rst:L216-L230, docs/r_comparison.rst:L399-L415, and docs/r_comparison.rst:L433-L436 say HAD has “no R parallel” and that the paper has not been packaged in R. As of April 26, 2026, the current package manuals already show DIDHAD and DIDmultiplegt(mode="had"); the R surface appears narrower/QUG-oriented, but it is not accurate to say there is no R counterpart at all. Concrete fix: narrow the claim to the actual gap, e.g. that diff-diff covers a broader HAD surface than the current R packages rather than “no R parallel.” (cran.r-universe.dev)

Not run here: Sphinx build/tests, due the read-only sandbox.

Path to Approval

1. Revert the HAD estimator SE-contract docs to the implemented split between deprecated weights= and survey_design=SurveyDesign(...), and remove survey_design=make_pweight_design(weights) from estimator-surface guidance.
2. Fix every newly added HAD snippet to use the real call signature and result fields (*_col, att, design).
3. Update docs/r_comparison.rst to reflect the current R ecosystem and describe the remaining gap precisely instead of saying there is no R parallel.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 9a62e922816c659dc795b08517642b4d4b3a7426

---

Overall Assessment

⚠️ Needs changes

The prior P1s from the last review look resolved, but two new unmitigated P1 methodology/doc mismatches remain on the changed HAD public surface.

Executive Summary

• The earlier blockers appear fixed: the new HAD examples now use the real *_col kwargs / result fields, and the estimator-side weighting docs now distinguish deprecated weights= from canonical survey_design=SurveyDesign(...).
• P1 [Newly identified]: docs/api/had.rst now tells users that qug_test uses survey_design=make_pweight_design(weights), but qug_test still permanently rejects all survey/weighted inputs.
• P1 [Newly identified]: the new troubleshooting text says “no exact dose == 0 implies Design 1 / WAS_d_lower”, but design="auto" also resolves to Design 1' when d.min() < 0.01 * median(|d|).
• P2: the R-comparison refresh is directionally better, but one claim in docs/r_comparison.rst still overstates the remaining gap versus DIDHAD.
• The newly documented HAD SE-family split / covariance limitations are already tracked in TODO.md, so those remain P3 informational only.

Methodology

• Severity: P1 [Newly identified]. Impact: docs/api/had.rst:L67-L72 says the array-in HAD pretest helpers, including qug_test, use survey_design=make_pweight_design(weights). That contradicts the actual QUG contract: qug_test documents survey_design= / survey= / weights= as permanently unsupported and raises NotImplementedError, and the Methodology Registry explicitly says make_pweight_design(arr) is not a valid QUG migration target (diff_diff/had_pretests.py:L1236-L1255, diff_diff/had_pretests.py:L1361-L1387, docs/methodology/REGISTRY.md:L2352-L2353). Concrete fix: remove qug_test from that list and say make_pweight_design() applies only to stute_test, yatchew_hr_test, and stute_joint_pretest; for weighted data, direct QUG remains unsupported and did_had_pretest_workflow(..., survey_design=...) intentionally skips it.
• Severity: P1 [Newly identified]. Impact: docs/troubleshooting.rst:L486-L490 says HAD routes to Design 1 whenever there are no exact dose = 0 rows. That is not the implemented default behavior: _detect_design() still resolves to continuous_at_zero / WAS when d.min() == 0 or when d.min() < 0.01 * median(|d|) (diff_diff/had.py:L1932-L1987, docs/methodology/REGISTRY.md:L2524-L2525). This misstates the public estimand-resolution contract and can make users misread results.target_parameter. Concrete fix: rewrite the troubleshooting cause to match the actual dispatch rule, including the small-positive-d_min Design 1' case.

Code Quality

No findings in the changed files.

Performance

No findings in the changed files.

Maintainability

No findings in the changed files.

Tech Debt

• Severity: P3 informational. Impact: docs/api/had.rst:L61-L77 documents the weighted SE-family split, next-minor API consolidation, and missing joint cross-horizon analytical covariance, and those limitations are already tracked in TODO.md:L93-L102. Concrete fix: none required in this PR.

Security

No findings.

Documentation/Tests

• Severity: P2. Impact: docs/r_comparison.rst:L227-L233, docs/r_comparison.rst:L420-L446 say diff-diff additionally covers the HAD multi-period event-study extension beyond DIDHAD. The current DIDHAD docs already expose dynamic effects, placebo, and event-study output in the QUG case, so the remaining gap is narrower than written. Concrete fix: narrow the comparison to the actual documented differences (e.g. Design 1 / no-QUG support and survey-design integration), or qualify the claim to the specific Appendix B.2 staggered/last-cohort surface if that is what you mean. (cran.r-universe.dev)

Not run here: local import/Sphinx smoke checks. This sandbox is missing numpy, and the workspace is read-only.

Path to Approval

1. In docs/api/had.rst, remove qug_test from the make_pweight_design() guidance and explicitly state that weighted/survey-aware QUG is unsupported.
2. In docs/troubleshooting.rst, replace the “no exact zero dose => Design 1” explanation with the implemented _detect_design() rule (d.min()==0 or d.min()<0.01*median(|d|) can still resolve to Design 1' / WAS).
3. In docs/r_comparison.rst, narrow the DIDHAD comparison so it does not imply that R lacks HAD event-study support altogether.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: f63f40be6c80e458cc7398c3b83effb988ae7fd4

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review scope: the prior P1s appear resolved. docs/api/had.rst now correctly treats qug_test as the exception to survey-aware migration, and the estimand-resolution troubleshooting text now matches _detect_design().
• The refreshed DIDHAD comparison is narrower than before and no longer makes the earlier overclaim about diff-diff being the only HAD event-study surface.
• One non-blocking docs mismatch remains in the new HAD troubleshooting section: it overstates when staggered multi-cohort event-study inputs raise versus when the estimator auto-filters.
• No code quality, performance, maintainability, or security findings in the changed files.

Methodology

• Severity: P2. Impact: docs/troubleshooting.rst:L572-L597 says HeterogeneousAdoptionDiD.fit(..., aggregate="event_study") raises when staggered timing violates the last-cohort restriction and recommends manual subsetting. The actual contract is narrower: with first_treat_col provided, the estimator auto-filters to the last-treatment cohort plus never-treated and emits a warning; it raises only when the panel is staggered and first_treat_col is missing. That behavior is implemented in diff_diff/had.py:L1230-L1366 and diff_diff/had.py:L1470-L1499, and documented in docs/methodology/REGISTRY.md:L2408-L2408 and docs/methodology/REGISTRY.md:L2533-L2533. Concrete fix: rewrite this troubleshooting entry to split the two cases explicitly and make first_treat_col the primary remedy; keep manual subsetting as optional equivalent guidance.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• Severity: P3 informational. Impact: the weighted SE-family split and missing joint cross-horizon analytical covariance are now clearly documented in docs/api/had.rst:L61-L95 and already tracked in TODO.md:L93-L102, so they are non-blocking per the review policy. Concrete fix: none required in this PR.

Security

• No findings.

Documentation/Tests

• No additional findings beyond the methodology/doc-contract issue above.
• Validation note: I could not run the Sphinx build here because sphinx is not installed in this environment.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 987bdcd42118bef761c202796cf0089671d706f3

---

Overall Assessment

⚠️ Needs changes

Executive Summary

• Re-review scope: the prior HAD event-study troubleshooting mismatch is resolved. docs/troubleshooting.rst:L572-L602 now matches the last-cohort auto-filter / raise split in diff_diff/had.py:L1233-L1360 and diff_diff/had.py:L1470-L1499.
• The new HAD API/pretest coverage is otherwise aligned with the exported public surface in diff_diff/__init__.py:L65-L81 and the registry notes in docs/methodology/REGISTRY.md:L2352-L2353 and docs/methodology/REGISTRY.md:L2488-L2505.
• One P1 remains in the new troubleshooting guidance: it says HeterogeneousAdoptionDiD() defaults to robust=True, but the constructor default is robust=False, so the suggested workaround would reproduce the same mass-point + survey vcov_type='classical' failure.
• One minor P3 docs mismatch remains: the weighted mass-point inference summaries omit supported CR1 clustered SEs.
• No code-quality, performance, maintainability, or security issues in the changed files.
• I could not rerun the Sphinx build here because python -m sphinx fails with No module named sphinx.

Methodology

• Severity: P1. Impact: docs/troubleshooting.rst:L559-L563 recommends HeterogeneousAdoptionDiD() as the fix for the mass-point + survey + classical-VCOV NotImplementedError and says the default is robust=True. The implementation default is robust=False at diff_diff/had.py:L2643-L2649, and the weighted mass-point survey guard explicitly treats that default mapping as classical and raises at diff_diff/had.py:L3418-L3447. A user following the docs would hit the same error instead of the advertised workaround. Concrete fix: replace the snippet with a working override such as HeterogeneousAdoptionDiD(vcov_type='hc1') or HeterogeneousAdoptionDiD(robust=True), and remove the incorrect “robust=True by default” comment.
• Severity: P3. Impact: docs/api/had.rst:L49-L54 and docs/choosing_estimator.rst:L665-L667 describe the deprecated weighted shortcut mass-point path as classical / hc1 only. The implementation and registry also support CR1 when cluster= is supplied on the weighted mass-point path, per diff_diff/had.py:L2276-L2284, diff_diff/had.py:L2433-L2448, and docs/methodology/REGISTRY.md:L2356-L2358 / docs/methodology/REGISTRY.md:L2527. This understates the supported inference surface. Concrete fix: clarify those summaries to say classical / hc1, plus CR1 when cluster= is supplied, or separate clustering from the vcov_type discussion.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• Severity: P3. Impact: the weighted-family split and missing joint cross-horizon analytical covariance called out in docs/api/had.rst:L61-L82 are already tracked in TODO.md:L93-L102, so they are non-blocking under the review policy. Concrete fix: none required in this PR.

Security

• No findings.

Documentation/Tests

• No additional findings beyond the methodology/doc-contract issues above.
• Validation note: I could not rerun the docs build because sphinx is not installed in this environment.

Path to Approval

1. Fix docs/troubleshooting.rst:L559-L563 so the recommended workaround actually selects HC1 on the mass-point survey path. The simplest correction is to show HeterogeneousAdoptionDiD(vcov_type='hc1') or HeterogeneousAdoptionDiD(robust=True), and state explicitly that plain HeterogeneousAdoptionDiD() keeps the default robust=False -> vcov_type='classical' mapping.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: ff6974104d2a25e43f0ca15445df440bca453d08

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review scope: the prior P1 on the HAD mass-point vcov_type="classical" workaround is resolved. docs/troubleshooting.rst:L541-L569 now matches the actual default mapping and guard in diff_diff/had.py:L2577-L2580 and diff_diff/had.py:L3415-L3447.
• The prior P3 on weighted mass-point CR1 support is also resolved. docs/api/had.rst:L49-L55 and docs/choosing_estimator.rst:L665-L667 now match the weighted 2SLS contract documented in docs/methodology/REGISTRY.md:L2355-L2360.
• The new HAD API/pretest coverage aligns with the exported public surface in diff_diff/__init__.py:L64-L82 and the registry notes for survey_design=, QUG-under-survey deferral, and variance-formula labels.
• One P2 doc-contract issue remains: the new prose overstates did_had_pretest_workflow as adjudicating the HAD design / dispatching by panel structure, but the actual API requires explicit aggregate= selection and the estimator, not the workflow, resolves continuous_at_zero vs continuous_near_d_lower vs mass_point.
• No P0/P1 methodology issues, no code-quality/performance/maintainability/security blockers in the changed files.
• I could not rerun the Sphinx build here because python -m sphinx fails with ModuleNotFoundError: No module named 'sphinx'.

Methodology

• Severity: P2. Impact: docs/api/had.rst:L130-L136, docs/practitioner_decision_tree.rst:L283-L301, and docs/r_comparison.rst:L227-L235 describe did_had_pretest_workflow as if it chooses the workflow shape from panel structure and/or adjudicates which HAD design path applies. In the implementation, the workflow has two explicit modes via aggregate= and requires callers to pass aggregate="event_study" on multi-period panels (diff_diff/had_pretests.py:L4033-L4045), while the HAD design itself is auto-resolved separately by _detect_design() from the dose support (diff_diff/had.py:L1932-L1987). A reader can reasonably expect automatic event-study dispatch or a pretest report that decides between continuous_at_zero, continuous_near_d_lower, and mass_point, but the API does neither. Concrete fix: rephrase the workflow as a diagnostic battery only; state explicitly that callers choose aggregate="overall" vs aggregate="event_study", and that HeterogeneousAdoptionDiD.fit() auto-detects the HAD design from the dose support.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• No new untracked tech-debt findings. The remaining HAD limitations newly documented in docs/api/had.rst:L62-L83 are already tracked in TODO.md:L93-L102, so they are non-blocking under the review policy.

Security

• No findings.

Documentation/Tests

• No additional findings beyond the P2 documentation-contract issue above.
• Validation note: I could not rerun the docs build in this environment because sphinx is not installed.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: db00262f7189f941f346c77021b534bb5f0c0f47

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review scope: the prior doc-contract issue is resolved. The updated prose now correctly separates pretest workflow dispatch from HAD design resolution in docs/api/had.rst:L130-L140, docs/practitioner_decision_tree.rst:L287-L310, and docs/r_comparison.rst:L233-L236, matching diff_diff/had_pretests.py:L4033-L4050 and diff_diff/had.py:L1932-L1987.
• The new HAD pretest/API coverage matches the exported public surface in docs/api/had.rst:L127-L183 and diff_diff/__init__.py:L69-L81, diff_diff/__init__.py:L468-L488.
• No unmitigated P0/P1 issues found. The refreshed survey/weighted, QUG-under-survey, mass-point-classical, and last-cohort event-study language aligns with docs/methodology/REGISTRY.md:L2352-L2382, diff_diff/had.py:L3399-L3447, diff_diff/had.py:L4147-L4181, diff_diff/had_pretests.py:L4081-L4160, and diff_diff/had.py:L1116-L1499.
• One P3 informational item remains: the new SE summaries still read as if weighted mass-point CR1 is unconditional when cluster= is supplied, but design="mass_point" + weights= + aggregate="event_study" + cband=True is still a documented exception (docs/api/had.rst:L49-L55, docs/choosing_estimator.rst:L665-L667, docs/methodology/REGISTRY.md:L2380-L2382, diff_diff/had.py:L4065-L4181).
• I could not rerun the docs build or runtime import smoke tests here because the environment is missing sphinx and numpy.

Methodology

• Severity: P3 (informational; deviation already documented in REGISTRY.md). Impact: docs/api/had.rst:L49-L55 and docs/choosing_estimator.rst:L665-L667 summarize the deprecated weights= mass-point path as supporting CR1 whenever cluster= is supplied. In implementation, the default weighted event-study path still rejects design="mass_point" + weights= + cluster= + cband=True (diff_diff/had.py:L4065-L4181), and that exception is explicitly documented in docs/methodology/REGISTRY.md:L2380-L2382. Concrete fix: add a short qualifier to the CR1 wording, e.g. “except aggregate="event_study", cband=True on the mass-point path,” or link that sentence to the existing exception note.
• No other findings.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• No new untracked tech-debt findings. The remaining HAD limitations referenced by these docs are already tracked in TODO.md:L93-L102.

Security

• No findings.

Documentation/Tests

• No additional findings.
• Validation note: static cross-check only. I could not rerun Sphinx or import-based validation in this environment because sphinx and numpy are unavailable.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: f43d737cb44dd090b2e6a1553b2cc26ba3ed4cdb

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review scope: the prior workflow/design-resolution documentation issue looks resolved. The new prose now correctly separates did_had_pretest_workflow() dispatch from HAD design auto-detection in docs/api/had.rst:L134-L144, matching diff_diff/had_pretests.py:L4033-L4050 and diff_diff/had.py:L1932-L1987.
• The new HAD API page covers the expected 12 public pretest symbols, and that list matches the top-level exports in diff_diff/__init__.py:L69-L81 and diff_diff/__init__.py:L474-L488.
• One residual informational issue remains in the SE contract docs: docs/api/had.rst:L49-L58 and docs/choosing_estimator.rst:L665-L667 still imply weights= + cluster= + aggregate="event_study" + cband=True can be made to work via vcov_type="hc1" / robust=True, but the implementation rejects that clustered combination outright, and also rejects mass-point survey_design + cluster= on the weighted path diff_diff/had.py:L3399-L3447, diff_diff/had.py:L4059-L4095, docs/methodology/REGISTRY.md:L2380-L2382.
• No unmitigated P0/P1 findings.
• Validation here was static only; I could not rerun the Sphinx build or import smoke tests because sphinx and numpy are not installed in this environment.

Methodology

• P3 Impact: docs/api/had.rst:L49-L58, docs/api/had.rst:L89-L100, and docs/choosing_estimator.rst:L665-L667 still overstate clustered weighted mass-point support. They frame the remaining blocker as the classical-default path, and suggest vcov_type="hc1" / robust=True as a workaround. In code, design="mass_point" + weights= + cluster= + aggregate="event_study" + cband=True is rejected regardless of vcov_type, and design="mass_point" + survey_design + cluster= is also rejected on the weighted path diff_diff/had.py:L3399-L3447, diff_diff/had.py:L4059-L4095. This deviation is already documented in docs/methodology/REGISTRY.md:L2380-L2382, so it is informational rather than blocking. Concrete fix: revise the prose to say those clustered combinations are unsupported outright, and remove the implication that hc1/robust=True enables the clustered cband=True path.
• No other findings.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• No new untracked tech-debt findings. The remaining HAD limitations referenced by these docs are already tracked in TODO.md:L93-L102.

Security

• No findings.

Documentation/Tests

• No additional findings.
• Validation note: static cross-check only. I could not rerun the docs build or import-based validation because sphinx and numpy are unavailable in this environment.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 96eb711ca6e59de4a17f596da2ece239893d88b5

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review scope: the prior weighted clustered-mass-point documentation gap is resolved. docs/api/had.rst:L49-L117 and docs/choosing_estimator.rst:L665-L667 now match the documented deviations in docs/methodology/REGISTRY.md:L2380-L2382 and the guards in diff_diff/had.py:L3399-L3447 and diff_diff/had.py:L4059-L4182.
• The new HAD pretests API page covers the expected public surface and matches the top-level exports in diff_diff/__init__.py:L69-L81 and diff_diff/__init__.py:L474-L488.
• The new narrative docs correctly separate pretest-workflow dispatch from estimator design auto-detection, consistent with docs/api/had.rst:L150-L160, docs/practitioner_decision_tree.rst:L287-L310, diff_diff/had_pretests.py:L4015-L4050, and diff_diff/had.py:L1932-L1987.
• One residual informational issue remains in troubleshooting: the mass-point paragraph describes the path as a fallback that “just changes the SE regime,” but the registry and implementation treat mass_point as a distinct Wald-IV / 2SLS estimator path as well as a different SE family.
• Validation here was static only; I could not rerun the Sphinx build or import smoke tests because sphinx and numpy are not installed in this environment.

Methodology

Affected methods reviewed: HeterogeneousAdoptionDiD and the HAD pretest surfaces did_had_pretest_workflow, qug_test, stute_test, yatchew_hr_test, stute_joint_pretest, joint_pretrends_test, and joint_homogeneity_test.

• P3 Impact: docs/troubleshooting.rst:L524-L539 frames mass-point resolution as a fallback to a “2SLS sandwich” that “just changes the SE regime.” In the registry and implementation, mass_point is a distinct Design 1 estimator path: the point estimate itself switches to the Wald-IV / 2SLS formula with instrument 1{D_2 > d_lower}, and the structural-residual sandwich is the corresponding inference path. The same paragraph also over-attributes that SE path to a paper appendix rather than to the library’s documented 2SLS implementation around the paper’s Section 3.2.4 design. Concrete fix: rephrase this subsection to say HAD auto-resolves to the mass-point design when the modal fraction at d_lower exceeds 2%; that design uses the mass-point Wald-IV / 2SLS estimator plus structural-residual sandwich inference. References: docs/troubleshooting.rst:L524-L539, docs/methodology/REGISTRY.md:L2400-L2402, docs/methodology/REGISTRY.md:L2523-L2527, diff_diff/had.py:L33-L39, diff_diff/had.py:L2260-L2272.

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• No new untracked tech-debt findings. The remaining HAD follow-ups referenced by the new docs are already tracked in TODO.md:L93-L102.

Security

• No findings.

Documentation/Tests

• No blocking documentation/test issues in the diff.
• Validation note: static cross-check only. I could not rerun the docs build or import-based smoke tests because sphinx and numpy are unavailable in this environment.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: b0399ee390a45370a1b9a671bbff048758d32e19

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review scope: the prior informational mass-point wording issue is resolved. docs/troubleshooting.rst:L518-L546 now describes mass_point as a distinct Design 1 Wald-IV / 2SLS path, matching docs/methodology/REGISTRY.md:L2400-L2402, docs/methodology/REGISTRY.md:L2523-L2528, and diff_diff/had.py:L33-L39, diff_diff/had.py:L2250-L2272.
• The refreshed inference-contract block in docs/api/had.rst:L43-L117 matches the documented HAD survey/weights deviations, including the weighted mass-point vcov_type="classical" guard and the cluster-combination rejections in docs/methodology/REGISTRY.md:L2352-L2382, diff_diff/had.py:L3399-L3447, and diff_diff/had.py:L4059-L4182.
• The new HAD pretests API section covers the exported public surface and correctly separates aggregate="overall" vs aggregate="event_study" workflow dispatch from estimator design auto-detection: docs/api/had.rst:L147-L205, diff_diff/__init__.py:L69-L81, diff_diff/__init__.py:L475-L488, diff_diff/had_pretests.py:L4033-L4050, diff_diff/had.py:L1932-L1987.
• The narrative additions in docs/choosing_estimator.rst:L364-L405 and docs/practitioner_decision_tree.rst:L266-L311 are consistent with the registry on Design 1' vs Design 1 targets and the non-testability of Assumptions 5/6 beyond the shipped pretests.
• Validation here was static only; I could not rerun Sphinx in this environment because python -m sphinx --version fails with No module named sphinx.

Methodology

No findings. The changed HAD docs align with the registry and implementation, and the only prior review issue was informational and is now resolved (docs/troubleshooting.rst:L518-L546, docs/methodology/REGISTRY.md:L2400-L2402, docs/methodology/REGISTRY.md:L2523-L2528, diff_diff/had.py:L2250-L2272).

Code Quality

No findings. The new API documentation covers the 12 exported HAD pretest symbols without inventing non-public surfaces (docs/api/had.rst:L147-L205, diff_diff/__init__.py:L69-L81, diff_diff/__init__.py:L475-L488).

Performance

No findings. This is a docs-only diff and it does not change runtime code paths.

Maintainability

No findings. The new doc-deps mappings improve drift coverage for HAD documentation rather than adding untracked coupling (docs/doc-deps.yaml:L386-L406).

Tech Debt

No findings. The limitations referenced by these docs remain tracked in TODO.md and/or documented as registry deviations, including weighted-event-study joint covariance and pending alias removal (TODO.md:L93-L104, docs/methodology/REGISTRY.md:L2380-L2382).

Security

No findings.

Documentation/Tests

No blocking documentation issues found in the diff. Static review only: Sphinx is not installed in this environment, so I could not rerun the docs build.