diff --git a/.claude/skills/doc-check/SKILL.md b/.claude/skills/doc-check/SKILL.md index 2d25fa2476fe2..3cfe79f2817c4 100644 --- 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 `` 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)* + +``` + +The `` marker goes last, so the next review can +find this comment. + ## What to Check - **Accuracy**: Does documentation match current code behavior? diff --git a/.github/workflows/doc-check.yaml b/.github/workflows/doc-check.yaml index a90a9a92ee2ac..f5f65a255c4f6 100644 --- a/.github/workflows/doc-check.yaml +++ b/.github/workflows/doc-check.yaml @@ -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 \`\` - 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)* - - \`\`\` - - The \`\` 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 {