agents: add create-news skill and news entry review auditor (#4252) Agents sometimes name news entries `0000.<category>.md` when a PR does not exist yet, which causes filename collisions across concurrent PRs, or write overly verbose news fragments that make `CHANGELOG.md` hard to skim. Require news filenames to use a short, hyphenated descriptive term when no issue or PR number exists, and require news entries to be 1-2 sentence skimmable snippets. Add a `create-news` skill with workflow guidance and examples, and add a dedicated `News Entry Auditor` sub-agent to `review-code` to enforce news file naming, brevity, and formatting.
diff --git a/.agents/rules/news.md b/.agents/rules/news.md index 71e63f9..760ca46 100644 --- a/.agents/rules/news.md +++ b/.agents/rules/news.md
@@ -11,15 +11,26 @@ Before drafting any news entry, adhere strictly to the rules in `CONTRIBUTING.md` above. +## Filename +* Name files `news/<id>.<category>.md`. +* Use the GitHub issue or PR number for `<id>` when known; otherwise, use a + short, hyphenated descriptive term (e.g., `my-feature.added.md`) to avoid + filename collisions. +* Never use generic placeholders like `0000`. + +## Brevity and Content +* Write a short snippet (1-2 concise sentences) so the combined `CHANGELOG.md` + is easy to skim and grok. +* State high-level, user-visible behavior and outcomes (what now works, what + changed). +* Omit internal implementation details, refactoring mechanics, and exhaustive + edge-case explanations (document detailed usage in API docs instead). + ## Sphinx MyST Cross-Reference Syntax (`{obj}`) * Use `{obj}\`<symbol>\`` only for cross-referencable Starlark or Python API symbols (rules, macros, targets, providers, attributes, args). * Never use `{obj}` on metadata files (e.g. `RECORD`), file paths, or tools. -## Content -* State user-visible behavior and outcomes (what now works, what changed). -* Omit internal implementation and refactoring details. - ## GitHub Issue Link Formatting * Append GitHub issue cross-references at the end of news entries in markdown link format:
diff --git a/.agents/skills/create-news/SKILL.md b/.agents/skills/create-news/SKILL.md new file mode 100644 index 0000000..b286132 --- /dev/null +++ b/.agents/skills/create-news/SKILL.md
@@ -0,0 +1,65 @@ +--- +name: create-news +description: Create or update a concise news entry file in `news/` for + user-visible changes +--- + +Use this skill when adding or editing a news fragment in `news/`. News entries +are combined into `CHANGELOG.md` at release time and must be short snippets that +are easy to skim and grok. + +@.agents/rules/news.md + +### Workflow + +1. **Determine if a News Entry is Needed**: + - Create a news file only for released, user-visible changes (`added`, + `changed`, `fixed`, `removed`). + - Skip news files for internal refactoring, test-only changes, or fixes to + unreleased code. + - Never edit `CHANGELOG.md` directly for unreleased changes. + +2. **Choose the Filename (`news/<id>.<category>.md`)**: + - `<id>`: Use the GitHub issue or PR number if one exists (e.g., `4181`). + If no issue or PR exists yet, use a short, hyphenated descriptive term + (e.g., `py-typed-pyi-srcs.added.md`). Never use `0000` or generic + placeholders. + - `<category>`: Choose `added`, `changed`, `fixed`, or `removed`. + +3. **Draft a Short, Skimmable Snippet**: + - Keep the entry to 1-2 concise sentences stating *what* changed for users. + - Prefix with the subsystem in parentheses when applicable (e.g., `(pypi)`, + `(toolchains)`, `(gazelle)`, `(bzlmod)`). + - Omit leading bullet points (`*` or `-`). + - Cut implementation mechanics, internal helper names, and secondary + edge-case explanations; put detailed usage in API docstrings instead. + - Wrap lines at 80 columns. + - Append issue/PR links at the end when applicable: + `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`. + +### Examples + +**Good (concise and skimmable)**: +```markdown +(toolchains) Added the +{obj}`--@rules_python//python/config_settings:py_pbs_distribution` flag to +select stripped `python-build-standalone` runtime archives +([#4163](https://github.com/bazel-contrib/rules_python/issues/4163)). +``` + +```markdown +(coverage) Skip lcov report generation when no coverage data is collected. +``` + +**Bad (too verbose and detailed)**: +```markdown +(pypi) A {obj}`pip.parse` call for a Python version that has no interpreter for +the host platform is now skipped, like a version with no registered toolchain, +instead of failing the whole {obj}`pip` extension. A dependency that lists, +say, Python 3.9 no longer breaks every other hub on hosts that have no CPython +3.9 build, such as Windows on ARM64 +([#4184](https://github.com/bazel-contrib/rules_python/issues/4184)). +``` +*(Rewrite: `(pypi) Skip {obj}\`pip.parse\` calls for Python versions without a +host interpreter instead of failing the {obj}\`pip\` extension +([#4184](https://github.com/bazel-contrib/rules_python/issues/4184)).`)*
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index c995eaa..2d1d282 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -32,14 +32,13 @@ - Prompt file: `.agents/skills/review-code/review-docs-prompt.md` - Focus: Audits documentation (`.md`) changes and docs build targets against - `.agents/rules/docs.md`, `.agents/rules/news.md`, and `AGENTS.md`. + `.agents/rules/docs.md` and `AGENTS.md`. 4. **Contribution Guidelines Sub-Agent** (`Role: "Contributing Auditor"`): - Prompt file: `.agents/skills/review-code/review-contributing-prompt.md` - - Focus: Audits changes, requirements updates, directives, and news entry - files (`news/<id>.<category>.md`) against `CONTRIBUTING.md` and - `.agents/rules/news.md`. + - Focus: Audits changes, requirements updates, and version directives against + `CONTRIBUTING.md`. 5. **Project Conventions Sub-Agent** (`Role: "Project Conventions Auditor"`): - Prompt file: @@ -69,6 +68,14 @@ declarations in `MODULE.bazel` for `@pypi//<pkg>` references under `python/**`). +9. **News Entry Sub-Agent** (`Role: "News Entry Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-news-prompt.md` + - Focus: Audits `news/<id>.<category>.md` files for presence, naming (no + generic `0000` placeholders), brevity and skimmability, and formatting + against `.agents/rules/news.md` and + `.agents/skills/create-news/SKILL.md`. + ### Action Instructions - Immediately create a user-facing review artifact named `code-review-results.md` in the conversation artifact directory so progress
diff --git a/.agents/skills/review-code/review-contributing-prompt.md b/.agents/skills/review-code/review-contributing-prompt.md index f0c3986..6d24ed3 100644 --- a/.agents/skills/review-code/review-contributing-prompt.md +++ b/.agents/skills/review-code/review-contributing-prompt.md
@@ -2,35 +2,16 @@ Your sole task is to audit all local changes (`git diff`), commit messages, and PR metadata against `CONTRIBUTING.md` and project rules: -1. Read and strictly enforce `CONTRIBUTING.md`, all `.agents/rules/*.md` files - (especially `.agents/rules/news.md`), and `AGENTS.md`. -2. **News Entry File Audit**: - - Check if the PR introduces user-visible features (`feat:`), bug fixes - (`fix:`), behavioral changes (`changed:`), breaking changes, or removals - (`removed:`). If so, verify that a news fragment file is added under - `news/<id>.<category>.md`. - - Verify `CHANGELOG.md` is NOT modified directly for unreleased changes. - - Verify news filename format: `news/<id>.<category>.md` where `<id>` is the - PR or issue number (or placeholder ID) and `<category>` is strictly one of - `added`, `changed`, `fixed`, or `removed`. - - Verify news entry content rules: - - Brief, human-friendly description without leading bullet points (`*` - or `-`). - - Subsystem prefix in parentheses when applicable (e.g. `(gazelle) ...`, - `(cc) ...`). - - Use Sphinx MyST cross-reference syntax `{obj}\`<symbol>\`` for rules, - macros, targets, providers, attributes, and args. - - Append GitHub issue cross-references at the end in markdown link format: - `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`. - - Lines wrapped at 80 columns. -3. Verify that `{versionadded}` and `{versionchanged}` directives use +1. Read and strictly enforce `CONTRIBUTING.md`, all `.agents/rules/*.md` files, + and `AGENTS.md`. +2. Verify that `{versionadded}` and `{versionchanged}` directives use `VERSION_NEXT_FEATURE` for unreleased features and are placed at the end of the documentation text. -4. If locked/resolved requirements files (`requirements.txt`, `pyproject.toml`, +3. If locked/resolved requirements files (`requirements.txt`, `pyproject.toml`, `requirements.in`) were modified, verify that the associated `requirements.update` target was executed to keep locked requirement files in sync. -5. Ensure style and conventions described in `CONTRIBUTING.md` are respected +4. Ensure style and conventions described in `CONTRIBUTING.md` are respected across all changes. @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-docs-prompt.md b/.agents/skills/review-code/review-docs-prompt.md index 1010135..c04f3b2 100644 --- a/.agents/skills/review-code/review-docs-prompt.md +++ b/.agents/skills/review-code/review-docs-prompt.md
@@ -2,8 +2,8 @@ Your sole task is to audit all documentation (`.md`) changes and new `.bzl` APIs in `git diff` against the project's documentation rules: -1. Read and strictly enforce `.agents/rules/docs.md`, `.agents/rules/news.md`, - `AGENTS.md`, and `CONTRIBUTING.md`. +1. Read and strictly enforce `.agents/rules/docs.md`, `AGENTS.md`, and + `CONTRIBUTING.md`. 2. Check that lines wrap at 80 columns. 3. Ensure markdown filenames use hyphens (`-`) rather than underscores (`_`) (except news entry files under `news/`, which follow `<id>.<category>.md`). @@ -16,8 +16,5 @@ version numbers). 7. Check documentation build correctness: ensure new `.bzl` files or public APIs are included in `//docs:docs` or relevant docs build targets. -8. For any added or modified news entries in `news/`, verify they adhere to - `.agents/rules/news.md` and `CONTRIBUTING.md` (proper `<id>.<category>.md` - name, no leading bullets, subsystem prefix, `{obj}` refs, issue links). @.agents/skills/review-code/review-report-format.md
diff --git a/.agents/skills/review-code/review-news-prompt.md b/.agents/skills/review-code/review-news-prompt.md new file mode 100644 index 0000000..d7c72d7 --- /dev/null +++ b/.agents/skills/review-code/review-news-prompt.md
@@ -0,0 +1,39 @@ +You are a specialized News Entry Auditor sub-agent. +Your sole task is to audit `news/` fragment files and user-visible changes in +`git diff` against `.agents/rules/news.md`, +`.agents/skills/create-news/SKILL.md`, and `CONTRIBUTING.md`: + +1. Read and strictly enforce `.agents/rules/news.md`, + `.agents/skills/create-news/SKILL.md`, and `CONTRIBUTING.md`. +2. **Presence & Applicability**: + - Check if the diff introduces released, user-visible features (`feat:`), + bug fixes (`fix:`), behavioral changes (`changed:`), breaking changes, or + removals (`removed:`). If so, verify a news file exists under + `news/<id>.<category>.md`. + - Verify no news entry is added for internal refactoring or fixes to + unreleased code. + - Verify `CHANGELOG.md` is not modified directly for unreleased changes. +3. **Filename (`news/<id>.<category>.md`)**: + - Verify `<id>` is the GitHub PR/issue number, or a short, hyphenated + descriptive term when no PR/issue exists yet. + - Flag any generic placeholder ID such as `0000` (causes merge collisions). + - Verify `<category>` is strictly one of `added`, `changed`, `fixed`, or + `removed`. +4. **Brevity & Skimmability**: + - Verify each news entry is a short snippet (1-2 concise sentences) that is + easy to skim and grok when combined into `CHANGELOG.md`. + - Flag overly long, verbose entries or entries that explain internal + implementation details, background rationale, or exhaustive edge cases + (provide a shortened rewrite in your report). +5. **Formatting & Cross-References**: + - Verify no leading bullet points (`*` or `-`). + - Verify subsystem prefix in parentheses when applicable (e.g., `(pypi)`, + `(toolchains)`, `(gazelle)`). + - Verify `{obj}\`<symbol>\`` is used only for cross-referencable Starlark or + Python API symbols (never on metadata files like `RECORD`, file paths, or + tools). + - Verify GitHub issue cross-references at the end use markdown link format: + `([#1234](https://github.com/bazel-contrib/rules_python/issues/1234))`. + - Verify lines wrap at 80 columns. + +@.agents/skills/review-code/review-report-format.md