Correctness subagent should follow ADR references discovered in code during investigation

[fullsend-ai-retro]

What happened

On PR #5868, the review agent's correctness subagent (run 30845101251) investigated the glossary's env/runner_env merge semantics claim. It grepped Go source code, found the EnvConfig struct definition, and read a code comment stating Replaces runner_env (ADR 0055). Despite seeing this ADR reference, the subagent never read ADR 0055. It recognized that env is a struct (not a flat map) but concluded the glossary description was 'close enough' and filed no finding. The human reviewer (waynesun09) subsequently identified the same structural inaccuracy, plus the missing deprecation note and missing ADR 0055 citation — adding a third commit to the PR that could have been avoided.

What could go better

The correctness subagent's current guidance (in sub-agents/correctness.md) includes cross-file verification ('MUST read that file before asserting what it contains') and technical docs surface area rules, but neither instructs the agent to follow ADR references it discovers in code comments during its own investigation. The existing guidance in the orchestrator (skills/pr-review/SKILL.md) has the correctness subagent check 'design document alignment — if the plan references a design document or ADR, are the claims consistent with the referenced source,' but this is scoped to ADRs referenced by the plan/PR, not ADRs discovered in code during investigation.

This is a distinct gap from existing issues: #3007 covers ADRs cited in PR descriptions; #269 covers plan/spec documents linked from PR descriptions; #1568 covers superseded ADRs in ADR files. None cover the pattern where the agent discovers an ADR reference in source code during its own investigation and should follow it.

Confidence: High. The transcript shows the agent saw 'ADR 0055' in the code comment and did not read it. Reading it would have provided unambiguous evidence of the deprecation and struct semantics.

Proposed change

Add guidance to sub-agents/correctness.md in the fullsend-ai/agents repo, in the 'Technical documentation with correctness surface area' section or as a new 'Reference discovery during investigation' section:

1. Follow discovered ADR/doc references: When you read source code or configuration during investigation and encounter a reference to an ADR, design doc, or spec (e.g., a code comment like // See ADR-0055 or // Replaces X (ADR-NNNN)), read the referenced document before finalizing your assessment. ADR references discovered in code are as important as those cited in the PR — they often contain deprecation notices, precise semantics, or constraints that the PR text omits.

2. Do not dismiss structural inaccuracies in reference documentation: When reviewing documentation whose purpose is to describe technical semantics (glossary entries, architecture docs, API reference), report discrepancies between the documentation and verified code/ADR behavior as findings rather than rationalizing them as 'close enough.' A glossary entry that says 'env merges as a map' when env is actually a struct with independent sub-maps is a medium-severity accuracy finding, not a tolerable simplification.

Validation criteria

On the next 3 docs PRs in fullsend-ai/fullsend that describe technical merge/composition/configuration semantics, the correctness subagent should: (1) follow any ADR references it discovers in code during investigation (observable in the transcript as Read tool calls to ADR files discovered during grep/code-reading, not just ADRs cited in the PR), and (2) report structural inaccuracies in reference documentation rather than dismissing them. Success means no human reviewer needs to catch an accuracy issue that the agent saw evidence for but dismissed.

---

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

[fullsend-ai-prioritize]

RICE Priority Score: 2.4

Score breakdown

Dimension	Score	Reasoning
Reach	1.5	This affects all users who rely on the PR review agent's correctness subagent for documentation and technical PRs across the organization. The specific scenario—ADR references discovered in code during investigation—applies to a moderate subset of reviews, but improving review agent accuracy benefits multiple teams and customers who depend on automated review quality.
Impact	1	Medium impact. When the agent encounters ADR references in code but fails to follow them, human reviewers must catch accuracy issues the agent had evidence for but dismissed, as demonstrated in PR #5868. Fixing this prevents missed findings and reduces reviewer burden, but workarounds exist (human reviewers still catch the issues). This is a noticeable workflow improvement rather than a blocker.
Confidence	0.8	High confidence. The issue is exceptionally well-described with a specific transcript-backed example, a clear root cause (agent saw 'ADR 0055' but didn't read it), precisely scoped proposed changes to sub-agents/correctness.md, and concrete validation criteria. The gap from existing issues (#3007, #269, #1568) is clearly articulated.
Effort	0.5	Simple, well-scoped change. The fix involves adding 1-2 paragraphs of guidance text to sub-agents/correctness.md in the 'Technical documentation with correctness surface area' section. The proposed wording is already drafted in the issue. No architectural changes, no multi-file modifications, no complex testing required.

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