From fb956f8b9d1faa909a1bbaa054d1d4516072f924 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Tue, 14 Jul 2026 04:10:45 +0000 Subject: [PATCH 1/7] Require sharing self-review notes on PRs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The PR template's self-review checkbox is unverifiable on its own — make the notes a required, shareable artifact: - self-review skill: new step to save each round's report and post all rounds on the PR (description or comment) - contribution guide: sharing the notes is part of the AI-assisted contribution workflow; a checked box without notes counts as not done - PR template: checkbox for having shared the notes - .ai/AGENTS.md: mention the notes-sharing step in the self-review section Co-Authored-By: Claude Fable 5 --- .ai/AGENTS.md | 2 +- .ai/skills/self-review/SKILL.md | 19 ++++++++++++++++++- .github/PULL_REQUEST_TEMPLATE.md | 1 + docs/source/en/conceptual/contribution.md | 4 +++- 4 files changed, 23 insertions(+), 3 deletions(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 9ba0b64c850b..3d02c9ccd311 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -40,4 +40,4 @@ Task-specific guides live in `.ai/skills/` and are loaded on demand by AI agents ## Self-review before a PR -Before opening a PR, run self-review against [review-rules.md](review-rules.md). The [self-review skill](skills/self-review/SKILL.md) runs this as the same pass the `@claude` CI reviewer uses. +Before opening a PR, run self-review against [review-rules.md](review-rules.md). The [self-review skill](skills/self-review/SKILL.md) runs this as the same pass the `@claude` CI reviewer uses. Save the report from every round and share the full notes on the PR (description or comment) — see the skill for details. diff --git a/.ai/skills/self-review/SKILL.md b/.ai/skills/self-review/SKILL.md index cfc45e54ebb0..2536ec9de4b5 100644 --- a/.ai/skills/self-review/SKILL.md +++ b/.ai/skills/self-review/SKILL.md @@ -14,7 +14,7 @@ Runs the same rubric as the `@claude` CI reviewer, so you catch issues before a maintainer does — but over your **whole** PR diff. (The CI scopes itself to `src/diffusers/` and `.ai/`; for your own PR, also review your tests, docs, and scripts.) You're already on the branch with the conventions loaded, so: get the -diff → review it against the rubric → report. +diff → review it against the rubric → report → save the notes to share on the PR. ## 1. Get the diff @@ -46,3 +46,20 @@ touched, also read `.ai/models.md`, `.ai/pipelines.md`, or `.ai/modular.md`. Report only — do not edit files. Be concrete, cite the rule, review the whole diff, and don't invent issues or flag pure style. + +## 4. Save the notes for the reviewer + +The report is not just for you — sharing it on the PR is part of the +contribution workflow (see the "AI-assisted and agentic contributions" section +of the contributor guide). Reviewers read it to see what was checked, what was +fixed, and what you deliberately left. + +- Save each round's full report to a local notes file (e.g. + `self-review-notes.md` outside the repo, or gitignored). Re-running + self-review after addressing findings or reviewer feedback is a **new + round** — append it with a heading (`## Round 2 — `); never overwrite + earlier rounds. +- When the PR is opened, post the complete notes — **all rounds** — in the PR + description or as a PR comment, including findings you intentionally did not + fix and why. +- Do not commit the notes file as part of the PR diff. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 55b148b0c10e..895fa0da29a4 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -19,6 +19,7 @@ Fixes # (issue) - [ ] Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so: - [ ] Did you read the [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents) guide? - [ ] Did you self-review the diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)? + - [ ] Did you share the self-review notes (all rounds) in the PR description or a comment? - [ ] Did you read the [contributor guideline](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution)? - [ ] Did you read our [philosophy doc](https://huggingface.co/docs/diffusers/main/en/conceptual/philosophy)? (important for complex PRs) - [ ] Was this discussed/approved via a GitHub issue or the [forum](https://discuss.huggingface.co/c/discussion-related-to-httpsgithubcomhuggingfacediffusers/63)? Please add a link to it if that's the case. diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index c332792fd3d0..8df7e6c044e8 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -593,7 +593,9 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Coordinate before opening a PR.** Find or open an issue, review similar PRs (open and recently closed), and wait for an explicit acknowledgment from a maintainer on that issue before opening a PR. This gives us a chance to discuss scope, avoid duplicate work, and confirm the approach. - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. -- **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill (or review your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)) and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — just add a brief note in the PR description for anything you intentionally skipped, so the reviewer knows it was a deliberate call. +- **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill (or review your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)) and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. +- **Share your self-review notes.** Post the full self-review report on the PR — in the description or as a comment. If you address findings (or reviewer feedback) and self-review again, that's a new round: share every round's notes, not just the latest, including findings you intentionally did not fix and why. A checked self-review box without the notes attached will be treated as if the self-review was not done. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). + - Your **self-review notes** (or a link to the PR comment containing them), as described above. From 89018de6136c95a0e5ed6ee4e4d02d28c9ec55bf Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Tue, 14 Jul 2026 07:19:29 +0000 Subject: [PATCH 2/7] Share only the final self-review round, not all rounds Co-Authored-By: Claude Fable 5 --- .ai/AGENTS.md | 2 +- .ai/skills/self-review/SKILL.md | 18 ++++++++---------- .github/PULL_REQUEST_TEMPLATE.md | 2 +- docs/source/en/conceptual/contribution.md | 2 +- 4 files changed, 11 insertions(+), 13 deletions(-) diff --git a/.ai/AGENTS.md b/.ai/AGENTS.md index 3d02c9ccd311..e7b34364d1fb 100644 --- a/.ai/AGENTS.md +++ b/.ai/AGENTS.md @@ -40,4 +40,4 @@ Task-specific guides live in `.ai/skills/` and are loaded on demand by AI agents ## Self-review before a PR -Before opening a PR, run self-review against [review-rules.md](review-rules.md). The [self-review skill](skills/self-review/SKILL.md) runs this as the same pass the `@claude` CI reviewer uses. Save the report from every round and share the full notes on the PR (description or comment) — see the skill for details. +Before opening a PR, run self-review against [review-rules.md](review-rules.md). The [self-review skill](skills/self-review/SKILL.md) runs this as the same pass the `@claude` CI reviewer uses. Share the final report on the PR (description or comment) — see the skill for details. diff --git a/.ai/skills/self-review/SKILL.md b/.ai/skills/self-review/SKILL.md index 2536ec9de4b5..7a138ce2dd17 100644 --- a/.ai/skills/self-review/SKILL.md +++ b/.ai/skills/self-review/SKILL.md @@ -47,19 +47,17 @@ touched, also read `.ai/models.md`, `.ai/pipelines.md`, or `.ai/modular.md`. Report only — do not edit files. Be concrete, cite the rule, review the whole diff, and don't invent issues or flag pure style. -## 4. Save the notes for the reviewer +## 4. Share the notes with the reviewer The report is not just for you — sharing it on the PR is part of the contribution workflow (see the "AI-assisted and agentic contributions" section of the contributor guide). Reviewers read it to see what was checked, what was fixed, and what you deliberately left. -- Save each round's full report to a local notes file (e.g. - `self-review-notes.md` outside the repo, or gitignored). Re-running - self-review after addressing findings or reviewer feedback is a **new - round** — append it with a heading (`## Round 2 — `); never overwrite - earlier rounds. -- When the PR is opened, post the complete notes — **all rounds** — in the PR - description or as a PR comment, including findings you intentionally did not - fix and why. -- Do not commit the notes file as part of the PR diff. +- You may run several rounds (fix findings, re-run). Share the **final + round's** report — the one that reflects the diff you're actually + submitting — in the PR description or as a PR comment, including any + findings you intentionally did not fix and why. +- If you self-review again later (e.g. after addressing reviewer feedback), + post that round's report as a new PR comment. +- Do not commit the notes as part of the PR diff. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 895fa0da29a4..dc9453b71919 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -19,7 +19,7 @@ Fixes # (issue) - [ ] Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so: - [ ] Did you read the [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents) guide? - [ ] Did you self-review the diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)? - - [ ] Did you share the self-review notes (all rounds) in the PR description or a comment? + - [ ] Did you share the final self-review notes in the PR description or a comment? - [ ] Did you read the [contributor guideline](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution)? - [ ] Did you read our [philosophy doc](https://huggingface.co/docs/diffusers/main/en/conceptual/philosophy)? (important for complex PRs) - [ ] Was this discussed/approved via a GitHub issue or the [forum](https://discuss.huggingface.co/c/discussion-related-to-httpsgithubcomhuggingfacediffusers/63)? Please add a link to it if that's the case. diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index 8df7e6c044e8..ad38abb78430 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -594,7 +594,7 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Coordinate before opening a PR.** Find or open an issue, review similar PRs (open and recently closed), and wait for an explicit acknowledgment from a maintainer on that issue before opening a PR. This gives us a chance to discuss scope, avoid duplicate work, and confirm the approach. - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. - **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill (or review your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)) and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. -- **Share your self-review notes.** Post the full self-review report on the PR — in the description or as a comment. If you address findings (or reviewer feedback) and self-review again, that's a new round: share every round's notes, not just the latest, including findings you intentionally did not fix and why. A checked self-review box without the notes attached will be treated as if the self-review was not done. +- **Share your self-review notes.** Post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. If you self-review again after addressing reviewer feedback, post that round's report as a new comment. A checked self-review box without the notes attached will be treated as if the self-review was not done. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). From 56292d9ef5560ed15411493fc6d3910316d8ea3e Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Tue, 14 Jul 2026 07:30:41 +0000 Subject: [PATCH 3/7] Mention self-review notes in the PR template intro comment Co-Authored-By: Claude Fable 5 --- .github/PULL_REQUEST_TEMPLATE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index dc9453b71919..7d2c58bf6637 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,6 +7,8 @@ Once merged, your PR is going to appear in the release notes with the title you Then, please replace this with a description of the change and which issue is fixed (if applicable). Please also include relevant motivation and context. List any dependencies (if any) that are required for this change. +If you used an AI agent, also include your final self-review notes here (or post them as a comment) — the report from the last self-review round, including any findings you intentionally did not fix and why. See https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md + Once you're done, someone will review your PR shortly (see the section "Who can review?" below to tag some potential reviewers). They may suggest changes to make the code even better. If no one reviewed your PR after a week has passed, don't hesitate to post a new comment @-mentioning the same persons---sometimes notifications get lost. --> From 4a53550d80293b6f1f040cd09486eafa91f53f80 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Tue, 14 Jul 2026 07:45:42 +0000 Subject: [PATCH 4/7] Soften notes-sharing ask; skill iterates until ready then reminds to share Co-Authored-By: Claude Fable 5 --- .ai/skills/self-review/SKILL.md | 24 ++++++++++------------- docs/source/en/conceptual/contribution.md | 2 +- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/.ai/skills/self-review/SKILL.md b/.ai/skills/self-review/SKILL.md index 7a138ce2dd17..b962678d927c 100644 --- a/.ai/skills/self-review/SKILL.md +++ b/.ai/skills/self-review/SKILL.md @@ -14,7 +14,8 @@ Runs the same rubric as the `@claude` CI reviewer, so you catch issues before a maintainer does — but over your **whole** PR diff. (The CI scopes itself to `src/diffusers/` and `.ai/`; for your own PR, also review your tests, docs, and scripts.) You're already on the branch with the conventions loaded, so: get the -diff → review it against the rubric → report → save the notes to share on the PR. +diff → review it against the rubric → report → iterate with the contributor +until it's ready, then remind them to share the final notes on the PR. ## 1. Get the diff @@ -47,17 +48,12 @@ touched, also read `.ai/models.md`, `.ai/pipelines.md`, or `.ai/modular.md`. Report only — do not edit files. Be concrete, cite the rule, review the whole diff, and don't invent issues or flag pure style. -## 4. Share the notes with the reviewer +## 4. Iterate until ready, then share -The report is not just for you — sharing it on the PR is part of the -contribution workflow (see the "AI-assisted and agentic contributions" section -of the contributor guide). Reviewers read it to see what was checked, what was -fixed, and what you deliberately left. - -- You may run several rounds (fix findings, re-run). Share the **final - round's** report — the one that reflects the diff you're actually - submitting — in the PR description or as a PR comment, including any - findings you intentionally did not fix and why. -- If you self-review again later (e.g. after addressing reviewer feedback), - post that round's report as a new PR comment. -- Do not commit the notes as part of the PR diff. +Expect several rounds: the contributor addresses findings, you review again. +Keep working with them to fix as much as possible until the verdict is +**READY** — the **Leave for the actual review** items are the only ones that +should reach the reviewer unresolved. End the final round's report by +reminding the contributor to share it on the PR (description or a comment) — +it saves the reviewer a round of back-and-forth. Never commit the notes as +part of the diff. diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index ad38abb78430..1e2036051262 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -594,7 +594,7 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Coordinate before opening a PR.** Find or open an issue, review similar PRs (open and recently closed), and wait for an explicit acknowledgment from a maintainer on that issue before opening a PR. This gives us a chance to discuss scope, avoid duplicate work, and confirm the approach. - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. - **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill (or review your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)) and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. -- **Share your self-review notes.** Post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. If you self-review again after addressing reviewer feedback, post that round's report as a new comment. A checked self-review box without the notes attached will be treated as if the self-review was not done. +- **Share your self-review notes.** Please post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. It helps the reviewer see what has already been checked and which calls were deliberate, and usually saves a few rounds of back-and-forth. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. - The **test commands you ran** and their results (paste relevant output, not just "tests pass"). From a07bfd06d8cdd4b005f05e6fb8963b6df64ef09a Mon Sep 17 00:00:00 2001 From: YiYi Xu Date: Mon, 13 Jul 2026 21:48:06 -1000 Subject: [PATCH 5/7] Apply suggestion from @yiyixuxu --- .ai/skills/self-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ai/skills/self-review/SKILL.md b/.ai/skills/self-review/SKILL.md index b962678d927c..2114c91f887b 100644 --- a/.ai/skills/self-review/SKILL.md +++ b/.ai/skills/self-review/SKILL.md @@ -55,5 +55,5 @@ Keep working with them to fix as much as possible until the verdict is **READY** — the **Leave for the actual review** items are the only ones that should reach the reviewer unresolved. End the final round's report by reminding the contributor to share it on the PR (description or a comment) — -it saves the reviewer a round of back-and-forth. Never commit the notes as +it saves the reviewer a few rounds of back-and-forth. Never commit the notes as part of the diff. From 7f2129a3f9ebdc141400e2137f94b1387f97540b Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Tue, 14 Jul 2026 07:58:11 +0000 Subject: [PATCH 6/7] Point checkbox and guide at the self-review skill directly Co-Authored-By: Claude Fable 5 --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- docs/source/en/conceptual/contribution.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 7d2c58bf6637..e28a3cb96563 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -20,7 +20,7 @@ Fixes # (issue) ## Before submitting - [ ] Did you use an AI agent (Claude Code, Codex, Cursor, etc.) to help with this PR? If so: - [ ] Did you read the [Coding with AI agents](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution#coding-with-ai-agents) guide? - - [ ] Did you self-review the diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)? + - [ ] Did you run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill on the diff? - [ ] Did you share the final self-review notes in the PR description or a comment? - [ ] Did you read the [contributor guideline](https://huggingface.co/docs/diffusers/main/en/conceptual/contribution)? - [ ] Did you read our [philosophy doc](https://huggingface.co/docs/diffusers/main/en/conceptual/philosophy)? (important for complex PRs) diff --git a/docs/source/en/conceptual/contribution.md b/docs/source/en/conceptual/contribution.md index 1e2036051262..7f7d8bd77f29 100644 --- a/docs/source/en/conceptual/contribution.md +++ b/docs/source/en/conceptual/contribution.md @@ -593,7 +593,7 @@ AI-assisted contributions are welcome, but they must be coordinated, scoped, and - **Coordinate before opening a PR.** Find or open an issue, review similar PRs (open and recently closed), and wait for an explicit acknowledgment from a maintainer on that issue before opening a PR. This gives us a chance to discuss scope, avoid duplicate work, and confirm the approach. - **Fix patterns, not one-offs.** If you spot an recurring issue, search the codebase for similar instances and open a *single* issue with a clear, systematic scope (e.g. "fix mutable defaults across all schedulers") rather than many issues or PRs for individual instances. -- **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill (or review your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md)) and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. +- **Self-review before opening.** Run the [`self-review`](https://github.com/huggingface/diffusers/blob/main/.ai/skills/self-review/SKILL.md) skill — it reviews your diff against [`.ai/review-rules.md`](https://github.com/huggingface/diffusers/blob/main/.ai/review-rules.md), the same rubric the `@claude` CI reviewer uses — and address what it reports — it's a helper, not authoritative, and can be wrong. Focus on the blocking issues that make sense to you, and clean up dead/unused code as much as possible. If you disagree with a suggestion, it's fine to leave it for the reviewer to discuss after the PR is opened — the notes you share (see below) tell the reviewer it was a deliberate call. - **Share your self-review notes.** Please post the final self-review report — the round that reflects the diff you're submitting — on the PR, in the description or as a comment, including findings you intentionally did not fix and why. It helps the reviewer see what has already been checked and which calls were deliberate, and usually saves a few rounds of back-and-forth. - **Include in the PR description:** - A **coordination link** to the issue or discussion where a maintainer acknowledged the work. From 7bc1632aa0a02e1f2d859091f245b93b3d3443a6 Mon Sep 17 00:00:00 2001 From: yiyixuxu Date: Tue, 14 Jul 2026 08:03:17 +0000 Subject: [PATCH 7/7] Note human review comments as a source for agent doc gaps Co-Authored-By: Claude Fable 5 --- .ai/review-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ai/review-rules.md b/.ai/review-rules.md index c936082dcce5..32a55662b925 100644 --- a/.ai/review-rules.md +++ b/.ai/review-rules.md @@ -20,7 +20,7 @@ Common mistakes are covered in the common-mistakes / gotcha sections in [AGENTS. A PR can leave existing docs stale or surface a pattern worth recording. Scan the docs related to what the PR touches and flag updates as a **suggestions / additional info** section (not blocking): - **Usage docs.** New or changed public behavior — a new pipeline/model, a new argument, changed defaults, a renamed API — should have matching updates in `docs/`, docstrings, and examples. Flag any that now describe outdated behavior or that are missing for the new surface. -- **Agent docs.** If the review turns up a rule, pattern, or common gotcha that isn't written down yet — especially one the author got wrong or that you had to reason out — propose adding it to the relevant agent guide ([AGENTS.md](AGENTS.md), [models.md](models.md), [pipelines.md](pipelines.md), [modular.md](modular.md), a skill, or this file) so the next contributor/agent gets it for free instead of repeating the mistake. +- **Agent docs.** If the review turns up a rule, pattern, or common gotcha that isn't written down yet — especially one the author got wrong or that you had to reason out — propose adding it to the relevant agent guide ([AGENTS.md](AGENTS.md), [models.md](models.md), [pipelines.md](pipelines.md), [modular.md](modular.md), a skill, or this file) so the next contributor/agent gets it for free instead of repeating the mistake. Human review comments on the PR are a good source for these: if a human reviewer pointed something out and your review missed it, that usually indicates a doc gap — figure out what's missing and propose the addition. ## Dead code analysis (new models)