Document exact AI reviewer deviation label formats

[igerber]

Summary

• Add "Documenting Deviations (AI Review Compatibility)" section to CLAUDE.md with the exact label patterns the AI reviewer recognizes
• Update dev-checklists.md methodology item to specify reviewer-recognized labels instead of generic "add a Note"
• Add Section 2.5 (Methodology Documentation Check) to pre-merge-check.md as a co-change warning
• Add Methodology Deviation Documentation checklist under "If Methodology Files Changed"
• Remove redundant REGISTRY.md line from Documentation Sync checklist (now covered by methodology checklist)

Methodology references (required if estimator / math changes)

• N/A — no methodology changes

Validation

• Tests added/updated: No test changes (documentation-only PR)
• Backtest / simulation / notebook evidence: N/A

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

[github-actions]

Overall Assessment

⚠️ Needs changes

Executive Summary

• No estimator, weighting, variance/SE, identification, or default-behavior code changed; the risk here is whether the new documentation accurately states the reviewer contract.
• The new “exact reviewer-recognized labels” guidance is wrong in three places: it documents **Note**: and **Deviation from R**: instead of **Note:** and **Deviation from R:**.
• Because the guidance is framed as exact, following it can still leave a methodology deviation unmitigated and trigger a P1 “undocumented methodology deviation” review finding.
• The new TODO guidance is aligned with the current table structure and categories in TODO.md:38-60.
• No runtime, performance, or security issues were introduced by this docs-only PR.

Methodology

• Severity: P1. Impact: CLAUDE.md:94-106, .claude/commands/dev-checklists.md:48-55, and .claude/commands/pre-merge-check.md:115-120 plus .claude/commands/pre-merge-check.md:152-155 all claim the reviewer-recognized labels are **Note**: and **Deviation from R**:. This PR is explicitly documenting the exact accepted formats, but those strings do not match the review contract used here (**Note:**, **Deviation from R:**, **Note (deviation from R):**). A contributor who follows the new docs can still get a P1 “undocumented methodology deviation” finding. Concrete fix: replace the first two label spellings everywhere in this PR with the exact accepted strings **Note:** and **Deviation from R:**, keep **Note (deviation from R):** as-is, and use literal copy/paste examples in CLAUDE.md rather than variant formatting.

Code Quality

No findings.

Performance

No findings.

Maintainability

No findings.

Tech Debt

No findings.

Security

No findings.

Documentation/Tests

No additional findings beyond the methodology-documentation mismatch above. This is a docs-only PR; I did not see a separate test gap created by the changed behavior once the label strings are corrected.

Path to Approval

1. Update CLAUDE.md, .claude/commands/dev-checklists.md, and .claude/commands/pre-merge-check.md to use the exact reviewer-recognized label spellings: **Note:**, **Deviation from R:**, and **Note (deviation from R):**.
2. Re-scan the changed text for any remaining **Note**: / **Deviation from R**: variants so the PR no longer claims exact support for unrecognized forms.

[igerber]

/ai-review

[github-actions]

🔁 AI review rerun (requested by @igerber)

Head SHA: 9eac65058bac1cdb923ea7557e46c27138b15f6d

---

Overall Assessment

✅ Looks good

Executive Summary

• Re-review focus was the prior P1 on exact deviation-label spelling; that issue is resolved.
• The updated guidance now uses the reviewer-recognized labels in CLAUDE.md:L94-L115, .claude/commands/dev-checklists.md:L48-L55, and .claude/commands/pre-merge-check.md:L110-L155.
• The new TODO.md guidance matches the current Tech Debt from Code Reviews structure in TODO.md:L38-L60.
• This is a docs-only PR; no estimator, inference, weighting, identification, or default-behavior code changed.
• I did not identify any new unmitigated P0 or P1 issues in the changed text.

Methodology

• No findings. The previous label-format mismatch is fixed: the changed docs now reference **Note:**, **Deviation from R:**, and **Note (deviation from R):**, which matches the reviewer contract and existing registry usage such as docs/methodology/REGISTRY.md:L238-L241 and docs/methodology/REGISTRY.md:L924-L924.

Code Quality

• No findings. The edits are internally consistent, and removing the redundant REGISTRY reminder from the generic documentation checklist is a reasonable deduplication.

Performance

• No findings. Documentation-only change.

Maintainability

• No findings. Centralizing the reviewer-compatible label guidance in CLAUDE.md:L94-L115 should reduce future drift across contributor instructions and review checklists.

Tech Debt

• No findings. The added deferral instructions align with the current TODO table layout and category split in TODO.md:L38-L60.

Security

• No findings. No executable code, dependency surface, or secret-handling paths changed.

Documentation/Tests

• No findings. For a docs-only PR, the lack of test changes is acceptable. Residual risk is limited to future doc/reviewer drift, and this PR reduces that risk rather than introducing it.