docs(v4): diagnostic-family amendment - third object kind + RDPlot rename rows

[igerber]

Summary

• Spec section 3.5: diagnostics as a third object kind (amends the Phase 1 design per maintainer decisions locked 2026-07-19). Exactly one load-bearing bit: estimator results carry the canonical inference quintet; diagnostic results do not. Membership is the library's EXISTING "Diagnostics & Sensitivity" docs family made checkable - parallel-trends testing, the placebo suite, HonestDiD, pre-trends power, power analysis, HAD pretests - with BaconDecomposition re-homed out of the API estimator roster at 4.0 and RDPlot consolidated under the unified family grouping. (A narrower classes-only tier with HonestDiD/PowerAnalysis carve-outs was drafted and rejected: the docs family already draws the right line.)
• The Diagnostic marker lives on RESULT containers (consumers hold results, not entry points): the enumerated roster spans Bacon/RDPlot/HonestDiD/pre-trends/power/placebo/HAD-pretest/DiagnosticReport result types, exempt from the section 5 quintet BY TYPE and isinstance-checkable so BusinessReport/DiagnosticReport/practitioner routing stop special-casing by name. Entry points are not marked; input shape (data-in vs results-in) is deliberately unconstrained; raw-dict functions and TWFEWeightsResult participate in the docs family only (explicit narrowing). No import-path moves; zero new classes beyond the single marker base.
• Ledger (75 rows): [M-091] gates the Phase 2 marker introduction with introduced_in: "3.9" - a 3.9 release cannot ship without the marker + its full-roster test (and the due gate now rejects evaluate as a dodge, with a regression fixture); [M-090] separately gates the 4.0 docs/roster reorganization; [M-088]/[M-089] migrate RDPlot.fit()'s post-freeze outcome_col/running_col params under the spec's missed-rename clause - the ledger's first live maintenance event, working as designed.

Forward-reference note for review: new locators on planned ledger rows name 3.9/4.0 surface that does NOT exist at HEAD - tests/test_v4_matrix.py asserts their ABSENCE until the owning phase ships.

Methodology references (required if estimator / math changes)

• Method name(s): No estimator code changes. Taxonomy/documentation only; the classification matches REGISTRY's existing language (RDPlot "NOT a treatment-effect estimator"; Bacon a diagnostic tool).
• Paper / source link(s): N/A - no methodology equations changed.
• Any intentional deviations from the source (and why): None.

Validation

• Tests added/updated: tests/test_v4_matrix.py - 170 checks green (75-row snapshot/floor, hardened introduced_in gate rejecting planned/evaluate, new regression fixture); ledger/spec crossrefs verified.
• Backtest / simulation / notebook evidence (if applicable): N/A - docs + ledger + test-count updates only; no public API or numerical behavior change.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

🤖 Generated with Claude Code

https://claude.ai/code/session_017eVKbBqzenDKa5idwtexQa

[github-actions]

Overall Assessment

⚠️ Needs changes — one unmitigated P1 release-contract gap.

Executive Summary

• No estimator, weighting, variance, inference, or identification logic changes.
• RDPlot and Bacon classifications agree with the Methodology Registry.
• M-091 can pass without propagating the new Diagnostic classification to reporting consumers.
• The proposed taxonomy is not identical to the “existing” documentation family as claimed.
• Static validation passed; pytest was unavailable in the runner.

Methodology

No findings. The Registry identifies RDPlot as non-estimating (docs/methodology/REGISTRY.md:L3975-L3985) and Bacon as a diagnostic (docs/methodology/REGISTRY.md:L4262-L4266).

Code Quality

No findings.

Performance

No findings; documentation and enforcement-test changes only.

Maintainability

M-091 does not gate promised consumer propagation

• Severity: P1
• Location: docs/v4-design.md:L184-L198, docs/v4-deprecations.yaml:L909-L920
• Impact: The required completion test covers only marker membership and serialization. It does not cover the promised BusinessReport/practitioner routing. Currently BusinessReport special-cases only Bacon (diff_diff/business_report.py:L177-L182), while practitioner routing treats unknown results as estimator results (diff_diff/practitioner.py:L111-L116). M-091 could therefore be marked done while RDPlot, power, and other diagnostic results remain silently misclassified.
• Concrete fix: Add diff_diff/business_report.py, diff_diff/practitioner.py, _reporting_helpers.py, and diff_diff/__init__.py to M-091’s scope. Require tests proving every marked diagnostic is rejected as BusinessReport’s primary estimator input and routed through diagnostic-specific handling—not generic estimator handling—in practitioner_next_steps().

Tech Debt

No findings.

Security

No findings; no secrets or executable security-sensitive changes detected.

Documentation/Tests

The claimed “existing” family does not match current documentation

• Severity: P2
• Location: docs/v4-design.md:L161-L168
• Impact: README currently places Bacon in the estimator list, includes Conley under Diagnostics, and omits several newly enumerated members (README.md:L123-L133). The Registry also places RDPlot outside its Diagnostics section. This makes the asserted source-of-truth rule ambiguous.
• Concrete fix: Describe this as a new canonical consolidation and explicitly list reclassified, docs-only, and embedded-method exceptions, including Conley and DiagnosticReport.

M-090 omits named documentation surfaces

• Severity: P2
• Location: docs/v4-deprecations.yaml:L898-L908
• Impact: The row promises API and roster reorganization but its code_refs omit docs/api/index.rst, which currently lists Bacon as an estimator (docs/api/index.rst:L6-L37).
• Concrete fix: Add the API roster and other named grouping/count files to code_refs; require the terminal test to assert their estimator/diagnostic grouping.

Path to Approval

1. Expand M-091’s required Phase 2 propagation and tests to cover BusinessReport and practitioner classification routing.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: c2c9a57c4969794093bfbdde76ea646c87313694

---

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator, weighting, variance, inference, or identification logic changed.
• RDPlot’s non-estimator and Bacon’s diagnostic classifications match the Methodology Registry.
• The previous P1 is resolved: M-091 now gates BusinessReport and practitioner consumer propagation.
• M-090 now covers the API roster, resolving the prior documentation-scope concern.
• Static schema and locator checks passed; pytest was unavailable in the runner.

Methodology

No findings. Registry support: RDPlot is explicitly not a treatment-effect estimator (docs/methodology/REGISTRY.md:L3975-L3989), and Bacon is explicitly a diagnostic tool (docs/methodology/REGISTRY.md:L4262-L4266).

Code Quality

Stale release-gate docstring

• Severity: P3
• Location: tests/test_v4_matrix.py:L422-L436
• Impact: The docstring says due introductions reject only planned, while the implementation correctly rejects both planned and evaluate.
• Concrete fix: Change the docstring to say “may no longer be planned or evaluate.”

Performance

No findings.

Maintainability

No findings. M-091 now names the reporting consumers and requires type-based routing tests (docs/v4-deprecations.yaml:L909-L920).

Tech Debt

No findings.

Security

No findings; no secrets or security-sensitive executable changes were introduced.

Documentation/Tests

No findings. The prior documentation concerns are resolved by the canonical-consolidation wording and M-090’s explicit API roster coverage (docs/v4-design.md:L161-L174, docs/v4-deprecations.yaml:L898-L908).

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: bd81206c1448fd162d42a8020f1de023732d743a

---

Overall Assessment

⚠️ Needs changes — one unmitigated P1 contract-enforcement gap.

Executive Summary

• No estimator math, weighting, variance, inference, or identification logic changed.
• RDPlot and Bacon classifications agree with the Methodology Registry.
• The previous P3 docstring mismatch is resolved.
• M-091 omits required DiagnosticReport marker propagation from its completion tests.
• Static syntax, 75-row uniqueness, code-reference, and cross-reference checks passed; runtime tests were unavailable because pytest/numpy are not installed.

Methodology

No findings. RDPlot is explicitly non-estimating (docs/methodology/REGISTRY.md:L3975-L3989), while Bacon is explicitly diagnostic (docs/methodology/REGISTRY.md:L4262-L4266).

Code Quality

No findings.

Performance

No findings.

Maintainability

[Newly identified] DiagnosticReport propagation is not release-gated

• Severity: P1
• Location: docs/v4-design.md:L190-L208; docs/v4-deprecations.yaml:L909-L920
• Impact: The spec requires DiagnosticReport to switch from result-name special-casing to the Diagnostic marker, but M-091’s completion criteria only test BusinessReport and practitioner_next_steps. M-091 can therefore reach done while DiagnosticReport still routes marked diagnostics through estimator/unknown-result behavior.
• Concrete fix: Add DiagnosticReport marker-based routing to M-091’s mandatory consumer tests. Test at least one non-Bacon marked result and ensure it is explicitly rejected or handled as a diagnostic, never processed through estimator fallback; retain and test Bacon’s intended read-out behavior.

Tech Debt

No findings.

Security

No findings.

Documentation/Tests

Public documentation index is outside M-090’s gate

• Severity: P2
• Location: docs/v4-deprecations.yaml:L898-L908; docs/index.rst:L170-L208
• Impact: The documentation homepage can continue listing Bacon under “Supported Estimators” even after M-090’s named surfaces pass.
• Concrete fix: Add docs/index.rst to M-090’s code_refs and terminal grouping test.

Path to Approval

1. Extend M-091’s completion criteria and future test_ref requirements to cover marker-based DiagnosticReport routing.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 1351a04a901f282a198a41e1d40093eee1f8997b

---

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator math, inference, weighting, assumptions, or defaults changed.
• RDPlot and Bacon classifications match the Methodology Registry.
• Previous P1 resolved: M-091 now gates DiagnosticReport marker routing.
• Previous P2 resolved: M-090 now includes docs/index.rst.
• Static ledger, reference, syntax, and cross-reference checks passed. Pytest was unavailable in the environment.

Methodology

No findings. Registry confirms RDPlot is not an estimator and Bacon is diagnostic (docs/methodology/REGISTRY.md:L3975-L3989, L4262-L4266).

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings. The previous marker-propagation gap is resolved (docs/v4-deprecations.yaml:L909-L920).

Tech Debt

No findings.

Security

No findings.

Documentation/Tests

No findings. The homepage is included in M-090’s gated surfaces (docs/v4-deprecations.yaml:L898-L908), and the evaluate bypass has regression coverage (tests/test_v4_matrix.py:L596-L650).