What happened
On PR #4534, the code agent created 4 markdown links with display text "Decision 1" pointing at design.md without fragment anchors. Human reviewer mareklibra pushed commit c36fcd4 to add the anchors manually. The retro agent filed issue #4539, and PR #4540 added a "Fragment anchors for heading references" subsection to workspaces/boost/AGENTS.md (lines 285-298). The new guidance tells agents to read the target file, find the matching heading, and convert it to a GitHub-style fragment — but unlike the adjacent "Relative markdown links" subsection (lines 266-283), it does not include a concrete shell-command verification step.
What could go better
The sibling "Relative markdown links" subsection includes an explicit ls <relative-path-from-link> verification command (line 282). The fragment-anchor subsection has no analogous verification. This matters because PR #4534 demonstrated that the code agent can have verification guidance available yet still skip it — on that PR the agent ran a cosmetic bash comment instead of the prescribed ls check, leading to a broken path that the review agent caught but that cost $4.90 in fix + re-review. Without a concrete verification command for fragment anchors, the same pattern could recur: the agent may construct a fragment from memory or assumption rather than confirming the heading actually exists in the target file. Confidence: moderate. The guidance's instruction to "Read the target file, find the matching heading" is clear in intent, but the PR #4534 precedent suggests that explicit shell-command verification is more reliably followed than prose instructions.
Proposed change
Add a verification block to the "Fragment anchors for heading references" subsection in workspaces/boost/AGENTS.md (after line 298, before the ## Build & verify section). The block should mirror the structure of the relative-link verification at lines 278-283:
Always verify the heading exists in the target file:
```bash
# From the repo root or the directory containing the target file:
grep -n '### Decision 1' <path-to-target-file>
This makes the verification step concrete and runnable, consistent with the adjacent subsection's pattern. The grep command confirms the heading text exists before the agent converts it to a fragment anchor.
## Validation criteria
The next 3 code agent PRs in the boost workspace that add cross-reference links with heading-specific display text should show the agent running a grep or similar command to verify the heading exists in the target file before constructing the fragment anchor. The review agent should flag any heading-referencing link whose fragment does not match an actual heading in the target document.
---
_Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/4540_
What happened
On PR #4534, the code agent created 4 markdown links with display text "Decision 1" pointing at
design.mdwithout fragment anchors. Human reviewer mareklibra pushed commitc36fcd4to add the anchors manually. The retro agent filed issue #4539, and PR #4540 added a "Fragment anchors for heading references" subsection toworkspaces/boost/AGENTS.md(lines 285-298). The new guidance tells agents to read the target file, find the matching heading, and convert it to a GitHub-style fragment — but unlike the adjacent "Relative markdown links" subsection (lines 266-283), it does not include a concrete shell-command verification step.What could go better
The sibling "Relative markdown links" subsection includes an explicit
ls <relative-path-from-link>verification command (line 282). The fragment-anchor subsection has no analogous verification. This matters because PR #4534 demonstrated that the code agent can have verification guidance available yet still skip it — on that PR the agent ran a cosmetic bash comment instead of the prescribedlscheck, leading to a broken path that the review agent caught but that cost $4.90 in fix + re-review. Without a concrete verification command for fragment anchors, the same pattern could recur: the agent may construct a fragment from memory or assumption rather than confirming the heading actually exists in the target file. Confidence: moderate. The guidance's instruction to "Read the target file, find the matching heading" is clear in intent, but the PR #4534 precedent suggests that explicit shell-command verification is more reliably followed than prose instructions.Proposed change
Add a verification block to the "Fragment anchors for heading references" subsection in
workspaces/boost/AGENTS.md(after line 298, before the## Build & verifysection). The block should mirror the structure of the relative-link verification at lines 278-283: