agents: require user-visible docs prose and workaround comments

.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.

.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

.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

.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