agents: require user-visible docs prose and workaround comments (#4271) 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.

diff --git a/.agents/rules/docs.md b/.agents/rules/docs.md
index 987dacf..d450a5e 100644
--- a/.agents/rules/docs.md
+++ b/.agents/rules/docs.md

@@ -9,6 +9,8 @@
 * 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 d9bf706..0f64a7d 100644
--- a/.agents/rules/starlark.md
+++ b/.agents/rules/starlark.md

@@ -79,6 +79,8 @@
   `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 c04f3b2..b215a1a 100644
--- a/.agents/skills/review-code/review-docs-prompt.md
+++ b/.agents/skills/review-code/review-docs-prompt.md

@@ -16,5 +16,7 @@
    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 9511344..ec718e5 100644
--- a/.agents/skills/review-code/review-starlark-prompt.md
+++ b/.agents/skills/review-code/review-starlark-prompt.md

@@ -17,5 +17,7 @@
 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