From 9669ddb2eb7b267e7ba81392868a41cc9073d294 Mon Sep 17 00:00:00 2001 From: Ben Potter Date: Fri, 11 Sep 2026 16:19:28 +0000 Subject: [PATCH] fix: link the page in every doc-check item and require the sticky marker --- .claude/skills/doc-check/SKILL.md | 39 ++++++++++++++++++++++++++++--- .github/workflows/doc-check.yaml | 5 ++-- 2 files changed, 39 insertions(+), 5 deletions(-) diff --git a/.claude/skills/doc-check/SKILL.md b/.claude/skills/doc-check/SKILL.md index 3cfe79f2817..026e60876b1 100644 --- a/.claude/skills/doc-check/SKILL.md +++ b/.claude/skills/doc-check/SKILL.md @@ -125,6 +125,23 @@ Every `[ ]` is work the author owes. Anything optional belongs in the sentence under an item, or nowhere. An item that says "consider" or "not strictly required" is not an item. +### Every item carries a link + +An item names a page, so it can always link that page. Give the published +URL, which is `https://coder.com/docs/` plus the path with the `docs/` +prefix and the `.md` suffix removed. `docs/ai-coder/ai-gateway/reference.md` +becomes `https://coder.com/docs/ai-coder/ai-gateway/reference`. + +Write the path in backticks so it is greppable, then link it, so a reader +can open the page in one click: + +```markdown +- [ ] `docs/ai-coder/ai-gateway/reference.md` ([open](https://coder.com/docs/ai-coder/ai-gateway/reference)) - What needs to change +``` + +A page this pull request creates has no published URL yet. Name the path in +backticks alone and say the page is new. + ### Links resolve on GitHub, not in the docs tree A relative docs link resolves against the repository in a comment and @@ -135,6 +152,18 @@ Link an anchor only when that heading exists on the base branch today. A heading this pull request generates does not exist yet, so name the endpoint or section in words instead. +### The marker is not optional + +The comment ends with ``, on its own line, every +time. It is how the next review finds this comment instead of posting a +second one, and how the Slack notice knows a review had findings. A +comment without it reads as silence to everything downstream. + +After you post or edit, read the comment back and confirm the marker is +there. If it is not, edit the comment to add it. This happened on +`coder/coder#28723`: the review found a real gap, posted it without the +marker, and the notice said "No docs needed". + ### One comment per pull request Search the pull request for `` and edit that @@ -156,12 +185,12 @@ Include only the sections that apply. ## Documentation Check ### Updates Needed -- [ ] `docs/path/file.md` - What needs to change -- [x] `docs/other/file.md` - This was addressed +- [ ] `docs/path/file.md` ([open](https://coder.com/docs/path/file)) - What needs to change +- [x] `docs/other/file.md` ([open](https://coder.com/docs/other/file)) - This was addressed - ~~`docs/removed.md` - No longer needed~~ *(reverted in abc123)* ### New Documentation Needed -- [ ] `docs/suggested/path.md` - What should be documented +- [ ] `docs/suggested/path.md` - What should be documented, on a page that does not exist yet > ⚠️ *Checked but no corresponding documentation changes found in this PR* --- @@ -169,6 +198,10 @@ Include only the sections that apply. ``` +Keep to this structure. Do not add sections it does not have, such as an +evidence block. The evidence belongs in your answer, not in the author's +comment. + The `` marker goes last, so the next review can find this comment. diff --git a/.github/workflows/doc-check.yaml b/.github/workflows/doc-check.yaml index f5f65a255c4..c326ed0cb3f 100644 --- a/.github/workflows/doc-check.yaml +++ b/.github/workflows/doc-check.yaml @@ -213,8 +213,9 @@ jobs: Use \`gh\` to read the PR details, the diff, and every comment. Follow the skill in full: its evidence discipline, its comment - rules, and its comment format. **Do not comment if no - documentation changes are needed.** + rules, and its comment format. Every item links its page, and the + comment ends with \`\` on its own line. + **Do not comment if no documentation changes are needed.** ## When the workspace is broken