Correctness sub-agent should validate doc comments against referenced struct fields

[fullsend-ai-retro]

What happened

On PR #5997, the human reviewer (waynesun09's inline comment) caught a MEDIUM finding: the StatusNotificationsReader interface doc comment at internal/config/interfaces.go:36 read "provides read access to status notification configuration (comment/reaction start & completion)" but StatusNotificationConfig has no Reaction field — only a Comment field. The correctness sub-agent in review run 31408420012 returned zero findings on the same commit, missing this entirely. The author accepted the finding and pushed a fix (commit 19db87c).

What could go better

The correctness sub-agent does not currently cross-reference doc comments on interfaces or types against the actual fields/methods defined on the struct they describe. When a PR introduces a new interface with a doc comment that enumerates capabilities, any capability not backed by an actual struct field is a factual inaccuracy in the code. This is a mechanical check — compare the nouns/capabilities listed in the doc comment against the field names in the referenced type — and is well-suited to the correctness dimension. Confidence: high. The human identified this in a single pass; the struct had only two fields (Comment and nothing else), making the mismatch unambiguous.

Proposed change

Add a check to the correctness sub-agent's instructions (in the review agent definition or the pr-review skill) that says: "When the diff adds or modifies an interface, type, or method with a doc comment that enumerates capabilities or fields (e.g., 'provides access to X/Y/Z'), verify that each enumerated item corresponds to an actual field, method, or type in the codebase. Flag any doc comment that references a capability or field name that does not exist in the referenced struct or interface as a MEDIUM finding." This could be added to the correctness sub-agent's dispatch prompt in the review orchestrator or to the pr-review skill's correctness checklist.

Validation criteria

On the next 5 review agent runs where the diff introduces or modifies a Go interface or type with a doc comment listing capabilities, the correctness sub-agent should verify each listed capability against the actual struct fields. Specifically, if a test PR is constructed with a doc comment referencing a non-existent field (similar to the 'reaction' case here), the correctness sub-agent should flag it at MEDIUM severity.

---

Generated by retro agent from fullsend-ai/fullsend#5997

[fullsend-ai-prioritize]

RICE Priority Score: 2.4

Score breakdown

Dimension	Score	Reasoning
Reach	1.5	This improves the correctness sub-agent used in all PR reviews across the platform. Doc comment/struct field mismatches can occur in any Go PR that introduces or modifies interfaces and types with capability-enumerating doc comments, affecting multiple teams and contributors. Score 1.5 for multiple strategic customers / broad internal tooling impact.
Impact	1	Medium impact. When the mismatch occurs, it results in factual inaccuracies in code documentation that can mislead developers. However, it is not blocking — human reviewers can and do catch these (as demonstrated in PR #5997). The improvement is a noticeable quality gain for the automated review workflow but has an easy workaround (human review).
Confidence	0.8	High confidence. The issue is exceptionally well-described with a concrete example (PR #5997, specific file and line), a clear proposed change (add instruction to correctness sub-agent prompt), and explicit validation criteria. The scope is well-bounded and the failure mode is unambiguous.
Effort	0.5	Simple change. The proposed fix is adding a specific instruction to the correctness sub-agent's dispatch prompt or checklist — essentially a prompt engineering change, not an architectural one. The issue itself describes exactly what the instruction should say. Testing requires constructing a test PR with a mismatched doc comment to verify detection.

Formula: (1.5 x 1 x 0.8) / 0.5 = 2.4