diff --git a/.agents/rules/news.md b/.agents/rules/news.md index 7946967ad4..71e63f94ff 100644 --- a/.agents/rules/news.md +++ b/.agents/rules/news.md @@ -12,9 +12,13 @@ Before drafting any news entry, adhere strictly to the rules in `CONTRIBUTING.md` above. ## Sphinx MyST Cross-Reference Syntax (`{obj}`) -* Use `{obj}\`\`` in news entries for rules, macros, targets, providers, - attributes, args, and any other cross-referencable Starlark or Python - objects. +* Use `{obj}\`\`` 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 diff --git a/.agents/rules/pr.md b/.agents/rules/pr.md index 20690eb6ab..7c49497a0c 100644 --- a/.agents/rules/pr.md +++ b/.agents/rules/pr.md @@ -43,3 +43,5 @@ Before drafting any pull request description, strictly adhere to the rules in conceptual level. Link related issues (e.g. `Work towards #`). * **Conciseness & Style (Strunk & White)**: Omit needless words. Use clear, active, and direct phrasing for *why* and *how*. +* **Preserve Existing Descriptions**: Preserve the author's wording unless + instructed to change it. Wrap bodies at 72 columns.