coder · bpmct · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/.claude/skills/doc-check/SKILL.md b/.claude/skills/doc-check/SKILL.md
@@ -44,7 +44,8 @@ writing them.
    - Or is everything already covered?
 
 6. **Report findings.** Use the method provided in the prompt, or if none
-   specified, summarize findings directly.
+   specified, summarize findings directly. When the prompt asks for a
+   comment on a pull request, follow [Writing the comment](#writing-the-comment).
 
 ## Evidence discipline
 
@@ -96,6 +97,81 @@ Follow this order on every review.
    `docs/reference/`. "The diff already updates its own reference page" is
    not a reason to skip the search.
 
+## Writing the comment
+
+### A finding needs a page and a sentence
+
+Name the page, and name the sentence that is now wrong or the list that is
+now missing an entry. If you cannot name both, you have a hunch, not a
+finding, and a hunch costs the author more than it saves.
+
+Two habits produce weak findings:
+
+- **Documenting the interface.** A button, a filter preset, or a dialog is
+  not a documented surface on its own. Flag it only when a page already
+  enumerates the thing it belongs to, such as a table of settings or a
+  list of filters.
+- **Filing on the nearest page instead of the right one.** An
+  admin-facing change does not belong on an agents page because that page
+  happens to mention a similar option. When no page is the right home,
+  say so in one sentence and file nothing.
+
+One surface earns one item. Do not split a single change into a required
+item plus two nearby suggestions.
+
+### Checkboxes are work, not opinions
+
+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.
+
+### Links resolve on GitHub, not in the docs tree
+
+A relative docs link resolves against the repository in a comment and
+404s. Write the path in backticks, or link the published page in full,
+such as `https://coder.com/docs/reference/api/enterprise`.
+
+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.
+
+### One comment per pull request
+
+Search the pull request for `<!-- doc-check-sticky -->` and edit that
+comment instead of adding another. Search again immediately before you
+post: a comment you wrote earlier in this same review counts, and reviews
+of one pull request can overlap. Edit it, never post a second.
+
+When a comment already exists, compare your findings against it. Check off
+`[x]` items that are now addressed, strike through items the code reverted,
+and add `[ ]` items for new gaps. If an item is checked but you cannot
+verify the documentation landed, add a warning note below it. If nothing
+meaningful changed, leave the comment alone.
+
+### Comment format
+
+Include only the sections that apply.
+
+```markdown
+## Documentation Check
+
+### Updates Needed
+- [ ] `docs/path/file.md` - What needs to change
+- [x] `docs/other/file.md` - This was addressed
+- ~~`docs/removed.md` - No longer needed~~ *(reverted in abc123)*
+
+### New Documentation Needed
+- [ ] `docs/suggested/path.md` - What should be documented
+  > ⚠️ *Checked but no corresponding documentation changes found in this PR*
+
+---
+*Automated review via [Coder Agents](https://coder.com/docs/ai-coder/agents)*
+<!-- doc-check-sticky -->
+```
+
+The `<!-- doc-check-sticky -->` marker goes last, so the next review can
+find this comment.
+
 ## What to Check
 
 - **Accuracy**: Does documentation match current code behavior?

@@ -203,61 +203,35 @@ jobs:
               ;;
           esac
 
-          # Build chat prompt with sticky comment logic
+          # Build the chat prompt. Durable rules live in the skill
+          # (.claude/skills/doc-check/SKILL.md), so this prompt stays short
+          # and carries only what changes per run.
           CHAT_PROMPT="Use the doc-check skill to review PR #${PR_NUMBER} in coder/coder.
 
           ${CONTEXT}
 
-          When creating a new workspace, use the \"coder-workflow-bot\" template.
+          Use \`gh\` to read the PR details, the diff, and every comment.
 
-          If a tool call fails with \`get workspace agents in latest build: unauthorized: rbac: forbidden\`, this chat has no working workspace. That is an infrastructure state, not a mistake in your command, so the same command fails again if you retry it.
+          Follow the skill in full: its evidence discipline, its comment
+          rules, and its comment format. **Do not comment if no
+          documentation changes are needed.**
 
-          Call \`start_workspace\` with no arguments to start the workspace this chat owns. If it answers \`workspace was deleted\` or \`chat has no workspace\`, the old one is gone: call \`list_templates\` to get the ID of the \`coder-workflow-bot\` template, then call \`create_workspace\` with that ID. Wait for the workspace to be ready, then run the failed tool call again.
+          ## When the workspace is broken
 
-          If \`start_workspace\` answers \`load workspace: unauthorized: rbac: forbidden\`, the workspace is dormant and you cannot repair it. Stop there.
+          A tool call that fails with \`unauthorized: rbac: forbidden\` is an
+          infrastructure state, not a bad command, so retrying the same
+          command changes nothing.
 
-          When you cannot repair the workspace, say that you could not review the PR, and name the error you got. Post no doc-check comment. Do not say or imply the docs are fine, because you did not read them.
+          Call \`start_workspace\` with no arguments. If it answers
+          \`workspace was deleted\` or \`chat has no workspace\`, call
+          \`list_templates\` for the \`coder-workflow-bot\` template ID, then
+          \`create_workspace\` with it, and run the failed call again. If it
+          answers \`load workspace: unauthorized: rbac: forbidden\`, the
+          workspace is dormant and you cannot repair it: stop, say you could
+          not review the PR, and name the error. Post no comment, and do not
+          imply the docs are fine, because you did not read them.
 
-          Use \`gh\` to get PR details, diff, and all comments. Look for an existing doc-check comment containing \`<!-- doc-check-sticky -->\` - if one exists, you'll update it instead of creating a new one.
-
-          Follow the skill's evidence discipline, including its mandatory
-          search: list every literal this diff changes, then search the whole
-          docs tree for each OLD literal before you decide. Do not review only
-          the files in the diff. Report each search you ran and what it
-          returned, and post nothing only after every search came back empty
-          outside \`docs/reference/\`.
-
-          **Do not comment if no documentation changes are needed.**
-
-          If a sticky comment already exists, compare your current findings against it:
-          - Check off \`[x]\` items that are now addressed
-          - Strikethrough items no longer needed (e.g., code was reverted)
-          - Add new unchecked \`[ ]\` items for newly discovered needs
-          - If an item is checked but you can't verify the docs were added, add a warning note below it
-          - If nothing meaningful changed, don't update the comment at all
-
-          ## Comment format
-
-          Use this structure (only include relevant sections):
-
-          \`\`\`
-          ## Documentation Check
-
-          ### Updates Needed
-          - [ ] \`docs/path/file.md\` - What needs to change
-          - [x] \`docs/other/file.md\` - This was addressed
-          - ~~\`docs/removed.md\` - No longer needed~~ *(reverted in abc123)*
-
-          ### New Documentation Needed
-          - [ ] \`docs/suggested/path.md\` - What should be documented
-            > ⚠️ *Checked but no corresponding documentation changes found in this PR*
-
-          ---
-          *Automated review via [Coder Agents](https://coder.com/docs/ai-coder/agents)*
-          <!-- doc-check-sticky -->
-          \`\`\`
-
-          The \`<!-- doc-check-sticky -->\` marker must be at the end so future runs can find and update this comment."
+          Create any new workspace from the \"coder-workflow-bot\" template."
 
           # Output the prompt
           {