redhat-developer / redhat-developer/rhdh-plugins
Fix misleading grep comment and strikethrough ordering in cancellation checklist
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 48
- Forks
- 120
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 337
Description
What happened
The code agent created PR #4588 adding a cancellation consistency checklist to workspaces/boost/AGENTS.md. The review agent found two documentation accuracy issues: (1) the grep example comment says "From the openspec change area directory" but the grep paths (workspaces/boost/openspec/, workspaces/boost/specifications/) are relative to the repository root — the command would fail if run from the stated directory; and (2) the preamble instructs applying strikethrough before starting the checklist, but step 5 defines how to apply strikethrough correctly, creating a potential ordering confusion. The human reviewer approved and merged without addressing either finding. No fix agent was triggered and no follow-up issue was auto-created.
What could go better
The code agent should have verified that the grep example's stated working directory matches the command's path assumptions. The grep command uses repo-root-relative paths (workspaces/boost/openspec/) while the comment says "From the openspec change area directory" — these are incompatible. This is a documentation accuracy gap the code agent could catch by running the example command from the stated directory during its verification phase. Confidence is high that finding 1 is a genuine defect; confidence is moderate on finding 2 (readers may naturally read the full checklist before starting). Notably, a similar grep accuracy issue was found in the same file on a different PR (#4547), suggesting this is a recurring pattern in boost AGENTS.md documentation.
Proposed change
In workspaces/boost/AGENTS.md, in the cancellation checklist's grep example block: change the comment from # From the openspec change area directory to # From the repository root. For the strikethrough ordering: either move the strikethrough formatting rules (currently step 5) to step 1 so they appear before other steps, or reword the preamble from "apply strikethrough ... and then verify" to "verify all cross-file references using this checklist, applying strikethrough as described in step 5."
Validation criteria
After the fix: (1) the grep example comment accurately states the working directory as the repository root, and (2) the strikethrough formatting rules are referenced or appear before the preamble's instruction to apply strikethrough. Verify by reading the section sequentially — a reader should never encounter an instruction to act before the rules for that action are defined.
Generated by retro agent from https://github.com/redhat-developer/rhdh-plugins/pull/4588
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 locate the cancellation checklist and its grep example. Read the section sequentially, checking that the working-directory comment matches the command paths and that strikethrough rules precede any instruction to apply them. Done means both documentation issues are corrected and the validation criteria hold.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100