What happened
On PR #609, the code agent added cross-reference links to docs/code.md#how-to-configure in AGENTS.md, docs/review.md, and docs/triage.md. The links were syntactically valid — the anchor exists — but the target section describes how to override a sandbox image, not skills. A reader following the link for skills guidance would land on an unrelated example.
Human reviewer ralphbean caught this: "The code.md#how-to-configure example overrides the sandbox image:, not skills: — someone clicking through for skills guidance lands somewhere else." The review agent's initial run did not flag this. The fix agent replaced the misleading cross-links with inline YAML examples in all 3 files.
What could go better
The review agent's correctness and docs-currency sub-agents verify that cross-reference anchors exist (catching dead links) but do not verify that the target content is topically relevant to the surrounding context. This is a distinct class of error — the link works but following it does not help the reader.
Validating relevance requires reading the target section and comparing its topic to the linking paragraph's topic. For documentation PRs, misleading cross-references are higher-impact than dead links because a dead link is obviously broken while a misleading link silently wastes the reader's time.
This is distinct from #265 (narrative consistency from synthesizing verified facts) and #375 (dead reference detection). Neither covers semantic relevance of link targets.
Confidence: High that this is a real gap. Moderate confidence in the proposed fix — semantic relevance comparison requires judgment that may produce some false positives on edge cases.
Proposed change
In skills/pr-review/sub-agents/correctness.md or skills/pr-review/sub-agents/docs-currency.md, add guidance: when the diff adds or modifies a cross-reference link in documentation, the sub-agent should read the first few paragraphs of the target section and verify it discusses the same topic as the linking context. If the target section covers a different concept (e.g., image overrides vs. skills overrides), emit a finding noting the reader would be directed to irrelevant content.
Scope this check to internal repo documentation links (not external URLs) to keep cost bounded.
Validation criteria
On the next 5 documentation PRs that add or modify internal cross-reference links, the review agent should flag cases where the target section topic clearly diverges from the linking context. Zero false negatives on obviously misleading links where the target section discusses a different feature than the surrounding text promises.
Generated by retro agent from #609
What happened
On PR #609, the code agent added cross-reference links to
docs/code.md#how-to-configurein AGENTS.md, docs/review.md, and docs/triage.md. The links were syntactically valid — the anchor exists — but the target section describes how to override a sandbox image, not skills. A reader following the link for skills guidance would land on an unrelated example.Human reviewer ralphbean caught this: "The code.md#how-to-configure example overrides the sandbox
image:, notskills:— someone clicking through for skills guidance lands somewhere else." The review agent's initial run did not flag this. The fix agent replaced the misleading cross-links with inline YAML examples in all 3 files.What could go better
The review agent's correctness and docs-currency sub-agents verify that cross-reference anchors exist (catching dead links) but do not verify that the target content is topically relevant to the surrounding context. This is a distinct class of error — the link works but following it does not help the reader.
Validating relevance requires reading the target section and comparing its topic to the linking paragraph's topic. For documentation PRs, misleading cross-references are higher-impact than dead links because a dead link is obviously broken while a misleading link silently wastes the reader's time.
This is distinct from #265 (narrative consistency from synthesizing verified facts) and #375 (dead reference detection). Neither covers semantic relevance of link targets.
Confidence: High that this is a real gap. Moderate confidence in the proposed fix — semantic relevance comparison requires judgment that may produce some false positives on edge cases.
Proposed change
In
skills/pr-review/sub-agents/correctness.mdorskills/pr-review/sub-agents/docs-currency.md, add guidance: when the diff adds or modifies a cross-reference link in documentation, the sub-agent should read the first few paragraphs of the target section and verify it discusses the same topic as the linking context. If the target section covers a different concept (e.g., image overrides vs. skills overrides), emit a finding noting the reader would be directed to irrelevant content.Scope this check to internal repo documentation links (not external URLs) to keep cost bounded.
Validation criteria
On the next 5 documentation PRs that add or modify internal cross-reference links, the review agent should flag cases where the target section topic clearly diverges from the linking context. Zero false negatives on obviously misleading links where the target section discusses a different feature than the surrounding text promises.
Generated by retro agent from #609