redhat-developer / redhat-developer/rhdh-plugins
Add grep verification step to fragment-anchor guidance in boost AGENTS.md
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 48
- Forks
- 120
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 337
Description
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_
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open workspaces/boost/AGENTS.md and compare the “Fragment anchors for heading references” subsection with the adjacent “Relative markdown links” verification block. Add the requested grep-based verification example before “Build & verify”; done means the guidance includes a concrete command confirming the referenced heading exists.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- shell
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100