From 4c68fa2cf84e4bdf4eb56050f57a7a747498bedd Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Wed, 14 Oct 2026 21:13:59 -0700 Subject: [PATCH] agents: require user-visible docs prose and workaround comments Agents sometimes document internal workarounds in user-facing reference docs or omit inline comments explaining why non-obvious code workarounds are needed. Update the documentation and Starlark rules and review prompts to keep docs focused on user-visible behavior and require comments on non-obvious workarounds stating the intent, why the direct approach fails, and why the workaround works. --- .agents/rules/docs.md | 2 ++ .agents/rules/starlark.md | 2 ++ .agents/skills/review-code/review-docs-prompt.md | 2 ++ .agents/skills/review-code/review-starlark-prompt.md | 2 ++ 4 files changed, 8 insertions(+) diff --git a/.agents/rules/docs.md b/.agents/rules/docs.md index 987dacfc93..d450a5e966 100644 --- a/.agents/rules/docs.md +++ b/.agents/rules/docs.md @@ -9,6 +9,8 @@ globs: docs/*.md * Act as an expert in tech writing, Sphinx, MyST, and markdown. * Wrap lines at 80 columns. * Use hyphens (`-`) in file names instead of underscores (`_`). +* Document user-visible behavior, not internal workarounds or implementation + details. * **How-to Guides (`docs/howto/`)**: * Prefer adding sections to an existing topical guide (e.g. `docs/howto/build-a-wheel.md`) over creating a separate granular file. diff --git a/.agents/rules/starlark.md b/.agents/rules/starlark.md index d9bf70633b..0f64a7d0c6 100644 --- a/.agents/rules/starlark.md +++ b/.agents/rules/starlark.md @@ -79,6 +79,8 @@ globs: "*.bzl,BUILD,BUILD.bazel,*.bazel" `is_linux_x86_64`), so that `select()` keys read as conditions. * **Docstring Formatting Invariants**: Use triple-quoted strings for multi-line docstrings without trailing backslashes (`\`) for line continuation. +* **Workaround Comments**: Comment non-obvious workarounds with the intent, why + the direct approach fails, and why the workaround works. * **No Bazel Copyright Headers**: Do not add Bazel copyright headers to new or existing files unless explicitly directed by the user. * **Line Length & Wrapping**: Wrap Markdown and Starlark lines to 80 columns in diff --git a/.agents/skills/review-code/review-docs-prompt.md b/.agents/skills/review-code/review-docs-prompt.md index c04f3b2cfa..b215a1a7a3 100644 --- a/.agents/skills/review-code/review-docs-prompt.md +++ b/.agents/skills/review-code/review-docs-prompt.md @@ -16,5 +16,7 @@ in `git diff` against the project's documentation rules: 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. Ensure docs describe user-visible behavior, not internal workarounds or + implementation details. @.agents/skills/review-code/review-report-format.md diff --git a/.agents/skills/review-code/review-starlark-prompt.md b/.agents/skills/review-code/review-starlark-prompt.md index 95113440f5..ec718e59e5 100644 --- a/.agents/skills/review-code/review-starlark-prompt.md +++ b/.agents/skills/review-code/review-starlark-prompt.md @@ -17,5 +17,7 @@ in `git diff` against the project's Starlark coding rules and conventions: 8. Prefer `types.is_*` helpers from `@bazel_skylib//lib:types.bzl` over `type(x)` comparisons. 9. Verify `config_setting` names start with `is_` (or `_is_` when private). +10. Verify non-obvious workarounds have comments stating the intent, why the + direct approach fails, and why the workaround works. @.agents/skills/review-code/review-report-format.md