docs(todo): reorganize into Actionable / Deferred / Reference buckets

[igerber]

Summary

• Reorganize TODO.md from undifferentiated by-category tables + an empty "Tier A" and a redundant Tier A-D pointer block into three top-level buckets: Actionable Backlog (Effort + Origin columns), Deferred / Documented (sub-grouped by blocker), and Reference / Status.
• Consolidations: the 8 near-identical vcov_type="conley" rows collapse into one grouped entry with per-estimator sub-bullets; the two performance sections merge; the Honest-DiD and CallawaySantAnna-Bootstrap checklists fold into their rows; the Standard-Error-Consistency prose cross-links the conley deferred group. R/Stata/Julia-parity items moved to Deferred → needs external reference; the empty "Tier A — Quick wins" section and the entire Tier A-D scaffold removed.
• Repoint the references that keyed off the removed ### Tech Debt from Code Reviews section name to the new structure: CLAUDE.md (deviation-documentation convention), .github/codex/prompts/pr_review.md (the CI reviewer's deferred-work mitigation rule, ×2), and the goodman-bacon / wooldridge paper-review pointers. The lone historical CHANGELOG.md mention is left as a past-tense release record.

Methodology references (required if estimator / math changes)

• Method name(s): N/A - documentation/config reorganization. No source, math, weighting, variance/SE, or methodology change.
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None. Every deferred item retains its file + reason, so existing documented deviations are preserved verbatim (relocated, not altered); 344 -> 265 lines is pure consolidation. The reviewer-prompt + CLAUDE.md edits only update section-name references so the deviation-mitigation grep keeps resolving after the rename.

Validation

• Tests added/updated: No test changes (no executable code touched).
• Backtest / simulation / notebook evidence (if applicable): N/A. Verified: no malformed markdown table rows; all source rows accounted for across the new buckets; no remaining ### Tech Debt from Code Reviews reference except the historical CHANGELOG entry; the AI-review deviation-grep targets (file + reason per item) preserved.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

🤖 Generated with Claude Code

[github-actions]

Overall Assessment

✅ Looks good

Executive Summary

• No estimator, math, weighting, variance/SE, assumptions, or defaults were changed.
• No methodology mismatch found against docs/methodology/REGISTRY.md; this is a TODO reorganization.
• One P2 documentation/tooling issue: the PR removes the canonical TODO.md “Tech Debt from Code Reviews” section while repo reviewer prompts and methodology notes still reference that exact section.
• No security, performance, or runtime code concerns.

Methodology

No P0/P1 findings.

Severity: P3
Impact: Documentation-only reorganization; affected methodology items remain tracked in TODO.md and key REGISTRY-backed deviations are still described as documented/deferred.
Concrete fix: None required for methodology correctness.

Code Quality

No findings. No executable code changed.

Performance

No findings. No runtime code changed.

Maintainability

Severity: P2
Impact: The new TODO structure removes the exact “Tech Debt from Code Reviews” anchor, but the review prompt still says deferred work is tracked under that section and uses that section as a mitigation condition. Some methodology paper notes also point readers to the old section name. This can create stale internal references and may make future review/tooling behavior less predictable. See TODO.md:L81-L83, .github/codex/prompts/pr_review.md:L57-L99, docs/methodology/papers/wooldridge-2023-review.md:L112, and docs/methodology/papers/goodman-bacon-2021-review.md:L14.
Concrete fix: Either keep a compatibility heading/anchor such as ### Tech Debt from Code Reviews under Deferred / Documented, or update the reviewer prompt and methodology-paper references to the new Actionable Backlog / Deferred / Documented terminology.

Tech Debt

Severity: P3
Impact: Some formerly review-originated actionable rows no longer have a PR column, so provenance is less uniform than before. This is not a correctness issue, but it weakens the audit trail for why a debt item exists.
Concrete fix: Add a PR or Origin column to the Actionable Backlog tables, or include origin tags inline for rows promoted from prior review debt.

Security

No findings. No secrets or executable workflow changes observed.

Documentation/Tests

Severity: P2
Impact: Same stale-reference issue noted under Maintainability; documentation references should be updated with the reorganization.
Concrete fix: Update the prompt/docs references or preserve the old anchor as an alias. No tests are required for this docs-only change.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: d05d5e4a547bb5663764945da00075b916d08b6e

---

Overall Assessment

✅ Looks good

Executive Summary

• Prior P2 stale-anchor finding is largely addressed: reviewer prompt, CLAUDE guidance, and Wooldridge note now reference Deferred / Documented / Actionable Backlog.
• No estimator, math, weighting, variance/SE, inference, assumptions, or defaults changed.
• No P0/P1 methodology or edge-case findings.
• One P2 documentation inconsistency remains in the changed Bacon paper note: it says a future audit is tracked in TODO, but REGISTRY already has the completed BaconDecomposition audit and TODO has no Bacon audit row.
• One P3 tracker-format wording issue: TODO describes a PR column, while actionable tables use Origin.

Methodology

Severity: P2
Impact: docs/methodology/papers/goodman-bacon-2021-review.md:L14 still says the BaconDecomposition REGISTRY replacement is pending and tracked under TODO.md “Deferred / Documented”. That no longer matches docs/methodology/REGISTRY.md:L3153-L3232, which already contains the authoritative BaconDecomposition section with completed PR-B audit checklist items, and TODO.md:L81-L123 has no Bacon audit row. This is not a runtime methodology defect, but it leaves source-material status misleading.
Concrete fix: Update the status paragraph to say the REGISTRY audit has landed, or add a real TODO row if there is still a pending Bacon follow-up.

Code Quality

No findings. No executable code changed.

Performance

No findings. No runtime code changed.

Maintainability

Severity: P3
Impact: TODO.md:L21 says “The PR column points…”, but the Actionable tables use Origin (TODO.md:L29, TODO.md:L56, TODO.md:L72) while Deferred tables use PR. Minor tracker ambiguity only.
Concrete fix: Change the sentence to “The Origin / PR column…” or standardize the column name across sections.

Tech Debt

No blocking findings. The reorganization preserves deferred-work buckets and the reviewer mitigation prompt now points to the new structure.

Security

No findings. Documentation-only changes; no workflow or secret-handling changes observed.

Documentation/Tests

Severity: P2
Impact: Same Bacon status mismatch noted under Methodology. It affects documentation accuracy, not statistical output.
Concrete fix: Bring the Goodman-Bacon paper review status in line with the current REGISTRY/TODO state. No tests are required for this docs-only PR.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: e16dfb652370a0853c67a2b8b5a3707838c1cdbc

---

Overall Assessment

✅ Looks good

Executive Summary

• Prior Bacon status finding is resolved: goodman-bacon-2021-review.md now points to the landed REGISTRY.md contract and METHODOLOGY_REVIEW.md marks Bacon complete.
• Prior TODO column wording issue is resolved: TODO.md:L21 now distinguishes Origin and PR.
• No estimator, math, weighting, variance/SE, identification assumption, or default behavior changed.
• One P3 guidance-template mismatch remains in CLAUDE.md; it is informational and not approval-blocking.

Methodology

No findings.

Severity: None
Impact: Documentation-only changes. docs/methodology/REGISTRY.md:L3153-L3232 remains the authoritative Bacon contract, and METHODOLOGY_REVIEW.md:L81 records Bacon as complete.
Concrete fix: N/A

Code Quality

No findings. No executable code changed.

Performance

No findings. No runtime code changed.

Maintainability

Severity: P3
Impact: CLAUDE.md:L108-L120 describes the new TODO format but shows a single Issue | Location | Origin | Priority template. Actionable rows now include Effort (TODO.md:L29-L30), while Deferred rows use PR (TODO.md:L87-L88). This could lead future contributors to add malformed tracker rows, but it does not affect current behavior.
Concrete fix: Replace the single template with two templates: Actionable = Issue | Location | Origin | Effort | Priority; Deferred = Issue | Location | PR | Priority.

Tech Debt

No blocking findings. The new Actionable Backlog and Deferred / Documented buckets preserve the tracked limitations and reviewer mitigation references.

Security

No findings. Documentation/config-only changes; no secret handling or workflow execution change observed.

Documentation/Tests

No additional findings beyond the P3 CLAUDE.md template mismatch above. git diff --check is clean. No test suite run; not needed for this docs-only reorganization.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: feb81a872e8172ac50d3cc4ee0ff72a9ca043dac

---

Overall Assessment

✅ Looks good

Executive Summary

• No estimator, math, weighting, variance/SE, identification, or default behavior changes were introduced.
• Prior CLAUDE.md TODO-template mismatch is resolved with separate Actionable and Deferred table shapes.
• TODO.md reorganization preserves deferred-work tracking under the new buckets.
• Bacon status now points to the landed REGISTRY contract and METHODOLOGY_REVIEW.md completion status.
• One P3 documentation cleanup remains: old Goodman-Bacon paper-review prose still describes a pre-audit Bacon limitation in present tense.

Methodology

Severity: P3
Impact: docs/methodology/papers/goodman-bacon-2021-review.md:L193-L198 still says bacon.py does not remap genuinely always-treated units and that the audit “needs to decide” what to do. That is stale relative to the new landed-status note at docs/methodology/papers/goodman-bacon-2021-review.md:L14, the authoritative REGISTRY contract at docs/methodology/REGISTRY.md:L3228-L3231, and METHODOLOGY_REVIEW.md:L81. This is not a methodology defect because REGISTRY is authoritative and correct.
Concrete fix: Mark the paragraph as historical/pre-audit, or replace it with a short pointer to the current always-treated remap note in REGISTRY.

Code Quality

Severity: None
Impact: No executable code changed.
Concrete fix: N/A

Performance

Severity: None
Impact: No runtime paths changed.
Concrete fix: N/A

Maintainability

Severity: None
Impact: The prior CLAUDE.md template issue is fixed at CLAUDE.md:L120-L130, with separate table shapes for Actionable and Deferred rows.
Concrete fix: N/A

Tech Debt

Severity: None
Impact: The new TODO.md structure documents Actionable Backlog, Deferred / Documented, and Reference / Status at TODO.md:L7-L21; reviewer mitigation references were updated in .github/codex/prompts/pr_review.md:L57-L108.
Concrete fix: N/A

Security

Severity: None
Impact: Documentation/config-only changes; no secret handling or workflow execution behavior changed.
Concrete fix: N/A

Documentation/Tests

Severity: P3
Impact: Same stale Goodman-Bacon prose noted above. It may confuse future readers of the paper-review file, but it does not affect the authoritative methodology contract.
Concrete fix: Update docs/methodology/papers/goodman-bacon-2021-review.md:L193-L198 to say the pre-audit deviation was superseded by the landed Bacon audit.

Validation: git diff --check reported no whitespace errors. No test suite run; not needed for this docs-only reorganization.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 18f13481400df92944dc3380e2483d52d18d83af

---

Overall Assessment

✅ Looks good

Executive Summary

• No executable estimator, inference, variance/SE, weighting, or default behavior changes were introduced.
• Prior Goodman-Bacon stale-prose finding is resolved: the paper review now marks the audit as landed and points readers to REGISTRY.
• TODO.md, CLAUDE.md, and the CI reviewer prompt now consistently recognize the new Actionable Backlog / Deferred / Documented buckets.
• git diff --check passed.
• One P3 documentation cleanup remains in the Goodman-Bacon paper-review prose; it is not a blocker because REGISTRY and code are authoritative and correct.

Methodology

Severity: P3
Impact: docs/methodology/papers/goodman-bacon-2021-review.md:L197 still describes the always-treated remap shorthand as 0 < first_treat <= min(time). The authoritative REGISTRY contract uses first_treat <= min(time), excluding only sentinels 0 and np.inf, and explicitly supports negative / zero-crossing time axes at docs/methodology/REGISTRY.md:L3228-L3231. This is not a methodology defect because REGISTRY and bacon.py are correct and authoritative.
Concrete fix: Change the parenthetical at docs/methodology/papers/goodman-bacon-2021-review.md:L197 to first_treat <= min(time), excluding the never-treated sentinels 0 and np.inf, optionally mentioning ordered-time logic.

Code Quality

Severity: None
Impact: No executable code changed.
Concrete fix: N/A

Performance

Severity: None
Impact: No runtime paths changed.
Concrete fix: N/A

Maintainability

Severity: None
Impact: The TODO-template mismatch from the prior review is fixed: CLAUDE.md:L110-L130 now documents separate table shapes for Actionable and Deferred rows.
Concrete fix: N/A

Tech Debt

Severity: None
Impact: The reviewer prompt now points mitigation rules at Deferred / Documented and Actionable Backlog (.github/codex/prompts/pr_review.md:L59-L100), matching the reorganized TODO structure (TODO.md:L7-L21).
Concrete fix: N/A

Security

Severity: None
Impact: Documentation/config-only change; no secret handling or workflow execution behavior changed.
Concrete fix: N/A

Documentation/Tests

Severity: P3
Impact: Same Goodman-Bacon wording cleanup noted above. It may confuse future readers of the non-authoritative paper-review file, but it does not affect methodology behavior or reviewer mitigation.
Concrete fix: Align the line with REGISTRY wording.

Validation: git diff --check passed. No test suite run; this is a docs-only reorganization.

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 10f3f6f0a233ef78bc16a7a69dd54817c961ada9

---

Overall Assessment

✅ Looks good

Executive Summary

• No executable estimator, inference, weighting, variance/SE, or default behavior changes were introduced.
• The prior Goodman-Bacon stale-prose issue is resolved: the paper review now matches the authoritative REGISTRY contract for always-treated remapping.
• TODO.md, CLAUDE.md, and the reviewer prompt now consistently point to Actionable Backlog and Deferred / Documented.
• Wooldridge deferred-work prose now points to the relocated TODO row.
• git diff --check passed; no tests were run because this is documentation/config-only.

Methodology

Severity: None
Impact: No methodology implementation changed. The changed Goodman-Bacon prose now matches REGISTRY.md on first_treat <= min(time), sentinel exclusions, ordered-time handling, and the documented inclusive-boundary deviation (docs/methodology/papers/goodman-bacon-2021-review.md:L197; docs/methodology/REGISTRY.md:L3228-L3231).
Concrete fix: N/A

Code Quality

Severity: None
Impact: No executable code changed.
Concrete fix: N/A

Performance

Severity: None
Impact: No runtime paths changed.
Concrete fix: N/A

Maintainability

Severity: None
Impact: The contributor guidance now documents the two TODO table shapes and their intended buckets, which matches the reorganized TODO.md structure (CLAUDE.md:L108-L130; TODO.md:L25-L78, TODO.md:L81-L155).
Concrete fix: N/A

Tech Debt

Severity: None
Impact: Deferred-work mitigation references in the reviewer prompt now point to Deferred / Documented and Actionable Backlog, matching the renamed TODO structure (.github/codex/prompts/pr_review.md:L57-L69, .github/codex/prompts/pr_review.md:L98-L105).
Concrete fix: N/A

Security

Severity: None
Impact: Documentation/config-only changes; no secrets, workflow execution paths, or dependency behavior changed.
Concrete fix: N/A

Documentation/Tests

Severity: None
Impact: The previous P3 Goodman-Bacon documentation issue is fixed, and the Wooldridge paper review now points to the relocated TODO row for the tracked aggregation deviation (docs/methodology/papers/goodman-bacon-2021-review.md:L14-L20, docs/methodology/papers/wooldridge-2023-review.md:L112).
Concrete fix: N/A

Validation: git diff --check passed. No test suite run.