diff --git a/.claude/skills/respond-to-review/SKILL.md b/.claude/skills/respond-to-review/SKILL.md new file mode 100644 index 00000000..bee5b62e --- /dev/null +++ b/.claude/skills/respond-to-review/SKILL.md @@ -0,0 +1,125 @@ +--- +name: respond-to-review +description: As the author of a GitHub pull request, answer its review findings and questions with Conventional Comments reply labels — `done`, `ack`, `disagree`, `thanks`, plus `note` and `question` — fix what needs fixing, and push. Use when a pull request you wrote receives review comments, or when asked to address a review. Never posts `reviewed` or `decision`, never approves, never merges. +--- + +# Respond to a review + +You are the author of the pull request: you wrote its code, and you are answering its review. +Every finding or question a reviewer raises gets an answer, in its own thread, and the answer +says what you did about it. A reviewer's `reviewed:` comment is not one of them: it closes their +review, raises no point and asks nothing, so it needs no reply. + +## 0. Language + +**Write every reply in the language the repository requires.** Look for it before posting: +`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, or any other contribution guide the repository keeps. +A rule there wins over everything else — including the language the reviewer wrote in, and the +language of this skill. Without such a rule, answer in the language of the comment you reply to. + +The same rule applies to everything else you write on the pull request: its title, its +description, and your commit messages, which a repository often constrains separately. + +Only the prose follows that language. Labels and identifiers (`done`, `disagree`, a function +name) are never translated. + +## 1. Conventional Comments + +Follow https://conventionalcomments.org/ and the extensions of the Conventional Comments Toolkit +(https://github.com/Reefact/conventional-comments-toolkit/blob/main/README.md). + +**Read the repository's configuration first**: `.conventional-comments.json` at the repository +root, if it exists. A reply label it disables does not exist for this repository: answer with +what it leaves enabled, or in plain text where replies need no label. + +**That file is not the whole configuration.** The labels in force come from three levels, merged +in this order: the toolkit's defaults, then the **organisation's configuration**, then the +repository's file, each overriding the previous one label by label; an **enterprise floor** can +then force some labels on. The organisation's configuration and the floor reach the extension +through the browser's enterprise policy, so you usually cannot see them. Therefore: + +- if the person you work for gives you the organisation's configuration, apply it before the + repository's file; +- otherwise, use only labels you can confirm: those the repository's file declares or enables, and + the toolkit's defaults it does not disable — never one the file disables. Do not guess an + organisation's custom labels; +- say in your report that the organisation's configuration was not visible to you, if it was not. + +Every reply starts with: + +`