redhat-developer / redhat-developer/rhdh-plugins

Add grep verification step to fragment-anchor guidance in boost AGENTS.md

Open Beginner friendly
#4,547 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation ready-for-triage ready-to-code workspace/boost
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.