Update documentation for v2.9.0

[igerber]

Summary

• Rewrite ROADMAP.md to reflect v2.9.0 status — shipped items cleaned up, Phase 10 credibility roadmap added
• Rewrite survey-roadmap.md — Phase 10 added with detailed specs, structure simplified, stale references fixed (samplics → current guidance), resolved deferred items removed
• Add WooldridgeDiD and StaggeredTripleDifference to llms-full.txt with full API signatures
• Add survey support section to llms-full.txt (SurveyDesign usage, replicate weights, subpopulation)
• Add WooldridgeDiD to llms.txt estimator list, survey section, and tutorial links
• Add WooldridgeDiD to llms-practitioner.txt decision tree (staggered + nonlinear branches)
• Add WooldridgeDiD, TripleDifference, StaggeredTripleDifference to choosing_estimator.rst comparison table and flowchart
• Remove stale "EfficientDiD covariates + survey not supported" note from choosing_estimator.rst
• Add WooldridgeDiD group and source mappings to doc-deps.yaml
• Remove 8 resolved items from TODO.md

Methodology references

• N/A — documentation only, no methodology code changes

Validation

• No test changes — documentation only

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

⚠️ Needs changes

Executive Summary

• The PR is docs-only, but it introduces a blocking methodology/support mismatch: new survey-support overviews now claim blanket survey_design support even though WooldridgeDiD still has no survey_design parameter.
• The new Wooldridge and staggered DDD method descriptions are otherwise broadly aligned with the Methodology Registry.
• The new survey roadmap wording for SyntheticDiD/TROP mixes TSL terminology into paths that the registry documents as Rao-Wu bootstrap-based.
• docs/llms-full.txt adds runnable examples that currently fail as written (survey_metadata.deff, subpopulation() return shape).
• The new StaggeredTripleDifference API snippet in llms-full.txt has already drifted from the live signature/defaults.

Methodology

• Severity P1. Impact: The PR now states that all estimators accept survey_design / survey weights, but the same PR also says WooldridgeDiD is the only estimator without survey_design, and the live WooldridgeDiD.fit() signature confirms there is no such parameter. This overstates implemented survey inference support for a live estimator and will cause users or downstream LLM tooling to promise a methodology path the library does not provide. Concrete fix: replace the blanket claims with wording that explicitly excludes WooldridgeDiD until Phase 10f, and add that exception anywhere survey support is summarized. References: docs/llms.txt:L98-L108, docs/llms-full.txt:L1523-L1526, ROADMAP.md:L29-L42, docs/survey-roadmap.md:L199-L204, diff_diff/wooldridge.py:L322-L332

• Severity P2. Impact: The new limitations table tells readers to use “TSL (strata/PSU/FPC) with bootstrap” for SyntheticDiD and TROP when replicate weights are unavailable, but the registry and estimator docstrings document the supported full-design path as Rao-Wu rescaled bootstrap, not TSL. That is a variance-method terminology mismatch in a survey-methodology roadmap. Concrete fix: reword those alternatives to “use a strata/PSU/FPC survey design with Rao-Wu rescaled bootstrap” (or equivalent full-design bootstrap wording). References: docs/survey-roadmap.md:L220-L224, diff_diff/synthetic_did.py:L218-L222, diff_diff/trop.py:L428-L432, docs/methodology/REGISTRY.md:L1290-L1290, docs/methodology/REGISTRY.md:L1744-L1744

Code Quality

• No findings in the changed files beyond the documentation/API drift noted below.

Performance

• No findings.

Maintainability

• Severity P2. Impact: The new StaggeredTripleDifference snippet in llms-full.txt no longer matches the live API: it omits epv_threshold, pscore_fallback, balance_e, and valid aggregate='all', and it documents aggregate='event_study' as the default although the code default is None. This is especially brittle because the registry explicitly records pscore_fallback="error" as a deliberate default change. Concrete fix: sync the snippet to the actual signature/defaults, or generate these LLM-facing signatures from the same source as the API docs. References: docs/llms-full.txt:L667-L699, diff_diff/staggered_triple_diff.py:L100-L108, diff_diff/staggered_triple_diff.py:L196-L207, docs/methodology/REGISTRY.md:L1430-L1435

Tech Debt

• No new blocker found. The survey-related TODO removals I spot-checked are consistent with the current registry/code state.

Security

• No findings.

Documentation/Tests

• Severity P2. Impact: Two newly added survey examples in docs/llms-full.txt are not executable as written. SurveyMetadata exposes design_effect, not deff, and SurveyDesign.subpopulation() returns a (SurveyDesign, DataFrame) pair, not a single object. These are copy-paste failures in newly added user-facing examples. Concrete fix: change the example to results.survey_metadata.design_effect and sub_sd, sub_data = sd.subpopulation(...), then show sub_data and sub_sd being used together in fit(). A lightweight docs-snippet smoke test would prevent this class of regression. References: docs/llms-full.txt:L1546-L1565, diff_diff/survey.py:L422-L447, diff_diff/survey.py:L682-L716

Path to Approval

1. Remove or qualify the new blanket survey-support claims so they no longer include WooldridgeDiD, and make the exception consistent across ROADMAP.md, docs/llms.txt, and docs/llms-full.txt.
2. Fix the SyntheticDiD/TROP replicate-weight alternative wording in docs/survey-roadmap.md so it points to the actual supported full-design bootstrap path rather than TSL.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 4cfd68f0512a8b880a99bbbccdcd1399cccd75e2

---

Overall Assessment

⚠️ Needs changes

Previous blocking survey-support drift is only partially resolved.

Executive Summary

• The prior P1 is not fully closed: ROADMAP.md and docs/llms-full.txt now correctly exclude WooldridgeDiD from current survey support, but docs/llms.txt still says all estimators accept survey_design, and docs/survey-roadmap.md still uses an outdated unsupported-set summary.
• The earlier non-blocking docs issues appear fixed: the llms-full.txt survey example now matches SurveyMetadata/SurveyDesign.subpopulation(), the Rao-Wu wording is corrected, and the StaggeredTripleDifference snippet matches the live signature.
• docs/llms.txt now has a minor internal count drift: it says there are 15 estimators while listing 16 items.
• I found no code, performance, security, or TODO-cleanup blockers in the changed files.

Methodology

• Severity P1. Impact: The re-review’s prior blocking finding remains partially unresolved. docs/llms.txt still states that all estimators accept survey_design, but the live WooldridgeDiD.fit() signature has no survey_design parameter, and both the registry and roadmap say Wooldridge survey support is only planned for Phase 10f. docs/survey-roadmap.md also leaves the replicate-weight support summary internally inconsistent by naming the wrong unsupported set. This overstates implemented survey-methodology support and can cause users or downstream LLM tooling to recommend a design-based inference path the library does not provide. Concrete fix: change the LLM-facing survey summary to explicitly exclude WooldridgeDiD, and normalize the replicate-weight/support counts to one denominator with Wooldridge called out as unsupported until Phase 10f. References: docs/llms.txt:L100-L108, docs/survey-roadmap.md:L53-L54, docs/survey-roadmap.md:L199-L204, ROADMAP.md:L31-L42, diff_diff/wooldridge.py:L322-L332, docs/methodology/REGISTRY.md:L1076-L1155

Code Quality

• No findings.

Performance

• No findings.

Maintainability

• No findings.

Tech Debt

• No findings. The TODO.md removals I spot-checked are consistent with current code and registry state.

Security

• No findings.

Documentation/Tests

• Severity P3. Impact: docs/llms.txt says the project has 15 estimators, but the same section enumerates 16 items including BaconDecomposition. That makes the new survey-support totals harder to interpret and increases future drift risk. Concrete fix: either remove the hard-coded count or make the intro explicit about whether BaconDecomposition is excluded from the estimator total, then reuse that same denominator everywhere coverage is summarized. References: docs/llms.txt:L5-L5, docs/llms.txt:L53-L68

Path to Approval

1. Update docs/llms.txt so the survey-support overview explicitly says WooldridgeDiD does not currently accept survey_design.
2. Update docs/survey-roadmap.md so the Phase 6 replicate-weight support summary uses the current unsupported set and denominator, and no longer contradicts the Wooldridge limitation section.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 078f48e7661daabd102d3b429ce35045baf23cc1

---

Overall Assessment

⚠️ Needs changes

This re-review closes the prior blocking survey-support drift in docs/llms.txt and docs/survey-roadmap.md, but two unmitigated P1 documentation mismatches remain in changed estimator-selection/support docs.

Executive Summary

• The previous P1 appears resolved: docs/llms.txt now explicitly excludes WooldridgeDiD from current survey_design support, and docs/survey-roadmap.md now treats Wooldridge survey support as future Phase 10f work. docs/llms.txt:100 docs/survey-roadmap.md:201
• Severity P1 [Newly identified]. docs/choosing_estimator.rst still says all estimators accept survey_design, but WooldridgeDiD.fit() has no survey_design parameter and the roadmap/registry both say that support is not implemented yet. docs/choosing_estimator.rst:596 diff_diff/wooldridge.py:322 ROADMAP.md:31
• Severity P1 [Newly identified]. The LLM-facing estimator-selection guides still route generic two-eligibility designs to TripleDifference only, even though the registry/source distinguish plain 2×2×2 DDD from StaggeredTripleDifference for staggered timing. docs/llms-full.txt:1635 docs/llms-practitioner.txt:167 docs/methodology/REGISTRY.md:1316 docs/methodology/REGISTRY.md:1414
• I found no code, performance, security, or TODO-cleanup blockers in this docs-only PR.

Methodology

Previous review finding resolved: the changed llms and survey-roadmap docs no longer overstate current Wooldridge survey support. Remaining findings:

• Severity P1 [Newly identified]. Impact: docs/choosing_estimator.rst now includes WooldridgeDiD in the estimator guide, but the same file’s survey-support section still says “All estimators accept an optional survey_design parameter,” with no Wooldridge exception. That contradicts the live WooldridgeDiD.fit() signature and the roadmap/registry, which all treat Wooldridge survey support as future work. This can cause users or downstream LLM tooling to recommend a survey-design inference path the estimator does not implement. References: docs/choosing_estimator.rst:109 docs/choosing_estimator.rst:596 diff_diff/wooldridge.py:322 docs/methodology/REGISTRY.md:1076 docs/survey-roadmap.md:222 ROADMAP.md:42 Concrete fix: update the survey-support intro to exclude WooldridgeDiD, and add an explicit Wooldridge row in the compatibility matrix showing survey support as not currently available.
• Severity P1 [Newly identified]. Impact: the selection guides remain methodologically inconsistent about DDD estimator choice. llms-full.txt and llms-practitioner.txt still map generic “two-criterion treatment” problems to TripleDifference, while the registry and source docstrings distinguish TripleDifference as the 2×2×2 / non-staggered DDD implementation and StaggeredTripleDifference as the staggered-adoption DDD estimator with group-time ATT(g,t). That can steer practitioners and LLMs to the wrong estimand and identification setup for staggered DDD designs. References: docs/llms-full.txt:663 docs/llms-full.txt:1635 docs/llms-practitioner.txt:167 diff_diff/triple_diff.py:16 diff_diff/staggered_triple_diff.py:47 docs/methodology/REGISTRY.md:1316 docs/methodology/REGISTRY.md:1414 Concrete fix: revise the estimator-selection tables/trees to distinguish TripleDifference for 2×2×2/non-staggered DDD from StaggeredTripleDifference for staggered timing with eligibility.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings.

Tech Debt

No findings. The TODO.md removals I spot-checked look consistent with current code/registry state, so this cleanup does not appear to hide live deferred blocker debt. TODO.md:59

Security

No findings.

Documentation/Tests

No additional findings beyond the methodology-facing documentation mismatches above. For a docs-only PR, the lack of test changes is reasonable.

Path to Approval

1. Update docs/choosing_estimator.rst so the survey-support section explicitly excludes WooldridgeDiD and adds a corresponding “not supported yet / Phase 10f” row in the matrix.
2. Update the estimator-selection guidance in docs/llms-full.txt and docs/llms-practitioner.txt to split DDD recommendations into TripleDifference for 2×2×2/non-staggered designs and StaggeredTripleDifference for staggered DDD designs.
3. Mirror that same DDD distinction in the top decision flow of docs/choosing_estimator.rst so the human-facing guide and LLM-facing guides stay aligned.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: b6b7e694254ed4b8849548d0f2e7fbff12c0b909

---

Overall Assessment

⚠️ Needs changes

One unmitigated P1 remains in the changed human-facing estimator-selection guide.

Executive Summary

• Previous re-review blockers are resolved: the docs now explicitly state that WooldridgeDiD does not yet accept survey_design, in line with the code and roadmap. See docs/choosing_estimator.rst:596-694, docs/llms.txt:98-108, docs/llms-full.txt:1526-1579, and docs/survey-roadmap.md:199-204,220-223.
• Previous DDD-routing issues in the LLM-facing guides are also resolved: they now distinguish simultaneous TripleDifference from staggered StaggeredTripleDifference. See docs/llms-full.txt:1635-1637 and docs/llms-practitioner.txt:167-169.
• Severity P1 [Newly identified]. The main “Start here” flowchart in docs/choosing_estimator.rst still has no DDD branch, so readers following the primary selection path are routed to non-DDD estimators even though the same file now lists TripleDifference and StaggeredTripleDifference as distinct methods. See docs/choosing_estimator.rst:13-31 and docs/choosing_estimator.rst:101-109.
• No estimator code, weighting, variance/SE logic, or assumption-check implementation changed in this PR. I found no code-quality, performance, security, or TODO-cleanup blockers in the changed files.
• Severity P3. The rewritten docs use inconsistent denominators for survey-support coverage counts (16 estimators overall vs 14 of 15 survey-design support vs 12 of 15 or 12 of 16 replicate-weight support), which is confusing but non-blocking. See docs/llms.txt:5, ROADMAP.md:31-35, docs/llms-full.txt:1571-1574, and docs/survey-roadmap.md:53-54.

Methodology

Previous P1s from the last review are addressed in the changed files.

• Severity: P1 [Newly identified]. Impact: the primary human-facing decision flow still never asks whether the design is a DDD / two-eligibility design. A simultaneous 2x2x2 DDD falls through to the generic 2x2/panel branches, and a staggered DDD with eligibility is routed to generic staggered-adoption estimators (CallawaySantAnna, EfficientDiD, ImputationDiD, TwoStageDiD, or the new WooldridgeDiD branch). That conflicts with the methodology registry, which treats TripleDifference and StaggeredTripleDifference as distinct estimators with different data structures and assumptions, and it also conflicts with this same file’s new quick-reference table. References: docs/choosing_estimator.rst:13-31, docs/choosing_estimator.rst:101-109, docs/methodology/REGISTRY.md:1316-1320, docs/methodology/REGISTRY.md:1414-1419. Concrete fix: add an explicit early flowchart question for DDD / eligibility-based treatment, with branches for TripleDifference in simultaneous 2x2x2 DDD and StaggeredTripleDifference in staggered timing + eligibility designs; keep WooldridgeDiD only in the non-DDD nonlinear branch.

Code Quality

• No findings in changed files.

Performance

• No findings in changed files.

Maintainability

• No findings in changed files. docs/doc-deps.yaml remains valid YAML.

Tech Debt

• No findings. The TODO.md removals appear consistent with current code/registry state and do not hide unresolved P1/P0 debt.

Security

• No findings.

Documentation/Tests

• Severity: P3. Impact: survey-support coverage counts are inconsistent across the rewritten docs, so readers cannot tell whether BaconDecomposition is being excluded from denominators or whether the counts are simply drifting. References: docs/llms.txt:5, ROADMAP.md:31-35, docs/llms-full.txt:1571-1574, docs/survey-roadmap.md:53-54. Concrete fix: standardize the counting convention and state explicitly when diagnostic-only BaconDecomposition is excluded from estimator counts.
• No test changes is reasonable for this docs-only PR.

Path to Approval

1. Update the main flowchart in docs/choosing_estimator.rst so DDD designs are handled explicitly before the generic staggered/non-staggered branches: TripleDifference for simultaneous 2x2x2 DDD, StaggeredTripleDifference for staggered timing + eligibility. This resolves the remaining P1 methodology mismatch and would move the assessment to ✅.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 67714b26723227d984ebcdeacfe7711a803509fc

---

Overall Assessment

⚠️ Needs changes

The prior blocker in the main estimator chooser is resolved: DDD is now handled first in docs/choosing_estimator.rst:15-31. But two new unmitigated P1 methodology/documentation mismatches were introduced in the changed guides.

Executive Summary

• The previous P1 in the main human-facing flowchart is fixed; docs/choosing_estimator.rst now routes DDD designs to TripleDifference / StaggeredTripleDifference up front in docs/choosing_estimator.rst:15-31.
• WooldridgeDiD is now repeatedly described as using ASF-based ATT for OLS as well as logit/Poisson, but the registry and code say OLS ATT(g,t) are direct saturated-regression coefficients; ASF is only the nonlinear path. The incorrect phrasing appears in ROADMAP.md:19, docs/choosing_estimator.rst:115-118, docs/llms-full.txt:719, docs/llms.txt:67, and docs/llms.txt:96.
• The practitioner “decision tree” still places the DDD question after terminal staggered / simple-2x2 branches, so both simultaneous and staggered DDD designs can still be routed to non-DDD estimators in docs/llms-practitioner.txt:142-169.
• The new StaggeredTripleDifference API link in docs/llms.txt:66 points to api/staggered_triple_diff.html, but there is no corresponding API page in docs/api/ and the class is not exposed from docs/api/index.rst:15-29.
• I did not find new code-quality, performance, security, or TODO-cleanup blockers in the changed files.

Methodology

Previous blocker resolved: the main estimator-selection flowchart now correctly distinguishes simultaneous DDD from staggered DDD in docs/choosing_estimator.rst:15-31.

1. Severity: P1. Impact: the PR’s new Wooldridge summaries collapse the OLS and nonlinear paths into one “ASF-based ATT / delta-method” description, which is not what the implementation does. The registry states that OLS ATT(g,t) are identified by the saturated ETWFE interaction coefficients, while only logit/Poisson use ASF-based ATT with nonlinear delta-method SEs in docs/methodology/REGISTRY.md:1094-1121. The code matches that split: OLS extracts coefficients directly in diff_diff/wooldridge.py:552-610, while ASF logic is only in the nonlinear paths starting at diff_diff/wooldridge.py:727-760. Concrete fix: update every changed occurrence to say OLS uses direct cohort×time ATT coefficients from the saturated ETWFE regression, while logit/Poisson use ASF-based ATT; only mention delta-method SEs where that is actually true.

2. Severity: P1. Impact: the practitioner guide is presented as a decision tree, but the DDD check still comes after the first terminal split. A simultaneous 2x2x2 DDD answers “NO” to “Is treatment adoption staggered?” and is sent to DifferenceInDifferences; a staggered DDD answers “YES” and is sent to generic staggered estimators before ever reaching the DDD branch in docs/llms-practitioner.txt:142-169. That conflicts with the registry, which treats TripleDifference and StaggeredTripleDifference as distinct methods with distinct data structures/assumptions in docs/methodology/REGISTRY.md:1316-1320 and docs/methodology/REGISTRY.md:1414-1419. Concrete fix: reorder the practitioner tree so the DDD question comes before generic staggered/simple-2x2 routing, mirroring the corrected docs/choosing_estimator.rst flow.

3. Severity: P3. Impact: the new StaggeredTripleDifference signature in docs/llms-full.txt:668-683 exposes cluster without the implementation caveat that analytical clustered SEs are not wired; the code only emits a warning in diff_diff/staggered_triple_diff.py:277-284, and the limitation is already documented in docs/methodology/REGISTRY.md:1549-1551. Because the deviation is documented in REGISTRY.md, this is informational rather than blocking under the review rubric. Concrete fix: add the same caveat to the LLM-facing signature note and point clustered users to n_bootstrap > 0.

Code Quality

No findings in changed files.

Performance

No findings in changed files.

Maintainability

No findings in changed files. docs/doc-deps.yaml parses cleanly.

Tech Debt

No findings. The TODO.md removals look consistent with current code/registry state and do not appear to suppress unresolved P0/P1 items.

Security

No findings.

Documentation/Tests

1. Severity: P2. Impact: docs/llms.txt:66 links StaggeredTripleDifference to api/staggered_triple_diff.html, but there is no docs/api/staggered_triple_diff.rst in the tree and StaggeredTripleDifference is not listed in docs/api/index.rst:15-29. That leaves a user-facing dead link in the LLM index. Concrete fix: either add a real API page/index entry for StaggeredTripleDifference or change the link to an existing page that documents the class.

No test changes is reasonable for a docs-only PR.

Path to Approval

1. Correct the Wooldridge wording across the changed docs so OLS is described as coefficient-based ETWFE, while logit/Poisson are described as ASF-based nonlinear paths. The affected changed locations are ROADMAP.md, docs/choosing_estimator.rst, docs/llms-full.txt, and both Wooldridge mentions in docs/llms.txt.
2. Rewrite the ASCII decision tree in docs/llms-practitioner.txt so DDD is checked before generic staggered/simple-2x2 routing, with explicit branches for simultaneous TripleDifference and staggered StaggeredTripleDifference.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 7736619592b227e5fb9132aaa0b907cb558e3b6f

---

Overall Assessment

Looks good

Executive Summary

• The previous P1 methodology findings are resolved: the Wooldridge docs now distinguish direct OLS ATT(g,t) coefficients from ASF-based nonlinear ATT in ROADMAP.md:L19-L19, docs/choosing_estimator.rst:L115-L118, docs/llms-full.txt:L717-L719, and docs/llms.txt:L67-L67.
• The DDD routing issue is also fixed: both chooser flows now ask about triple-difference designs before generic staggered/simple routing in docs/choosing_estimator.rst:L15-L31 and docs/llms-practitioner.txt:L142-L169.
• The survey-support rewrite is internally consistent with the registry and implementation: Wooldridge is now correctly excluded from survey_design support in docs/choosing_estimator.rst:L602-L700, and removing the old EfficientDiD covariates + survey_design warning matches docs/methodology/REGISTRY.md:L701-L707 and diff_diff/efficient_did.py:L331-L356.
• No unmitigated P0/P1 findings remain.
• Remaining issues are non-blocking: one P2 documentation gap around StaggeredTripleDifference API docs, and one P3 informational caveat for its cluster parameter.

Methodology

No unmitigated P0/P1 findings. The prior methodology blockers from the last AI review are addressed in the changed docs.

• Severity: P3 (informational). Impact: the new StaggeredTripleDifference signature in docs/llms-full.txt:L668-L683 exposes cluster without saying that analytical clustered SEs are still deferred. That behavior is already documented in docs/methodology/REGISTRY.md:L1549-L1551 and warned in diff_diff/staggered_triple_diff.py:L277-L284, so under the review rubric this is informational, not a defect. Concrete fix: add a one-line note in the llms-full section that clustered inference currently requires n_bootstrap > 0.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings. docs/doc-deps.yaml parses cleanly.

Tech Debt

• Severity: P3 (tracked in TODO.md). Impact: this PR heavily edits .txt AI guides, but those files still are not covered by doc-snippet smoke tests; that limitation is already tracked in TODO.md:L91-L93. Concrete fix: extend snippet smoke tests to .txt guides or add a dedicated validation job. No action required for this PR because the gap is already tracked.

Security

No findings.

Documentation/Tests

• Severity: P2. Impact: the new StaggeredTripleDifference entry in docs/llms.txt:L66-L66 no longer points to a 404, but the target API landing page still does not actually document the class: docs/api/index.rst:L15-L29 omits StaggeredTripleDifference, and docs/api/staggered.rst:L1-L125 only covers CallawaySantAnna and SunAbraham. Users still do not have estimator-specific API docs for SDDD. Concrete fix: add StaggeredTripleDifference to the API reference, expose it from docs/api/index.rst, and then point docs/llms.txt directly to that page.
• No test additions are needed for the docs-only methodology fixes otherwise. I did not run the test suite for this review.