docs(#4539): add fragment-anchor guidance for heading links - #4540
Conversation
Add a Fragment anchors for heading references subsection to the boost workspace AGENTS.md under Documentation conventions, after the existing Relative markdown links subsection. When a markdown link display text names a specific heading, the code agent should include the GitHub-style fragment anchor in the URL rather than linking to the document root. This prevents a usability gap where the reader expects to land at a specific section but instead arrives at the top of a long document. This convention was identified from PR #4534, where 4 links with display text Decision 1 pointed at design.md without the fragment anchor, requiring a manual fix commit from the reviewer. Closes #4539
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4540 +/- ##
=======================================
Coverage 62.06% 62.06%
=======================================
Files 2603 2603
Lines 104477 104477
Branches 29375 29363 -12
=======================================
Hits 64848 64848
Misses 39034 39034
Partials 595 595
*This pull request uses carry forward flags. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
|
🤖 Finished Review · ✅ Success · Started 12:53 PM UTC · Completed 12:57 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $0.65 |
|
Review — approveScope: documentation-only change — 1 file modified ( SummaryThis PR adds a "Fragment anchors for heading references" subsection to the boost workspace AnalysisIntent & coherence: The change directly addresses issue #4539, which was filed by the retro agent after PR #4534 required a manual reviewer commit to add missing fragment anchors to 4 cross-reference links. The scope is tightly bounded to the requested documentation addition — no unrelated changes. Correctness: The guidance is technically accurate. GitHub's heading-to-fragment rules (lowercase, spaces to hyphens, strip punctuation) are correctly summarized. The example fragment Placement: The new subsection is correctly inserted after the closing code block of "Relative markdown links" (line 278) and before "## Build & verify" (line 280). This maintains the logical document structure: both subsections live under "Documentation conventions" and address related markdown authoring concerns. Style/conventions: The formatting (H3 subsection, prose explanation, fenced code block example, closing directive) matches the adjacent "Relative markdown links" subsection's pattern. Consistent with the rest of the document. Security: No security implications — this is agent-facing documentation guidance only. Documentation currency: The change itself is documentation. The content is current and references the real heading from the design document that motivated issue #4539. VerdictClean documentation addition. No findings. |
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
fullsend-ai-review
Bot
added
the
ready-for-merge
|
🤖 Finished Retro · ✅ Success · Started 5:01 PM UTC · Completed 5:17 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $3.94 |
Retro: PR #4540 — Add fragment-anchor guidance for heading linksThis PR was a retro-driven AGENTS.md improvement that went through the full agent pipeline cleanly. The retro agent on PR #4534 identified that human reviewer mareklibra had to manually push commit What went well:
Existing issue evidence (not proposed as new issues):
One proposal filed: The new fragment-anchor guidance subsection lacks a concrete verification step, unlike its sibling "Relative markdown links" subsection which prescribes Proposals filed
|
1 participant
Add a Fragment anchors for heading references subsection to the boost workspace AGENTS.md under Documentation conventions, after the existing Relative markdown links subsection.
When a markdown link display text names a specific heading, the code agent should include the GitHub-style fragment anchor in the URL rather than linking to the document root. This prevents a usability gap where the reader expects to land at a specific section but instead arrives at the top of a long document.
This convention was identified from PR #4534, where 4 links with display text Decision 1 pointed at design.md without the fragment anchor, requiring a manual fix commit from the reviewer.
Closes #4539
Post-script verification
agent/4539-fragment-anchor-guidance)ebecaa74d12add1c9f62054f87db8ca2a14e1e71..HEAD)