playbook/antigravity-awesome-skills/skills/docs-guard/references/code-samples.md

Docs Guard — Code Sample Rules

A code sample is the most-trusted part of any documentation: readers paste it. That trust makes a broken sample worse than no sample.

Contents

• Shippable sample checklist
• Realistic data
• Secrets and credentials
• Error-path examples
• Language and environment tags
• Sample drift

Shippable sample checklist

Every sample must pass all of these:

1. Imports resolve — every import/require/use names a real module at the documented version.
2. APIs are real — every call verified per verification.md: name, argument order, defaults, return shape.
3. Self-contained or explicit — runs on a clean machine, or states its prerequisites immediately above the block ("requires the client from the previous step").
4. No local residue — no /Users/yourname/, no C:\Dev\, no machine-specific ports or hostnames; use placeholder conventions the project already uses.
5. Syntactically valid — parse it mentally line by line; when the runtime allows, actually run or lint it.
6. Output shown is output produced — if the sample shows a result, that result must be what the code yields, not an idealized version.

Realistic data

Use data that exposes the API's shape honestly: realistic field names, plausible values, at least one non-ASCII string where text handling matters. foo/bar hides bugs that "Café Münster" reveals — especially for the i18n-aware audience.

Secrets and credentials

• Placeholders that cannot be mistaken for real values: YOUR_API_KEY, example.com, RFC 5737 IPs (192.0.2.x), sk_test_… style markers only when the provider defines them.
• Never paste real-looking tokens — even invented ones train readers to paste theirs, and secret scanners will flag the repo.
• Auth setup goes in one place and is linked, not repeated with variations in every sample.

Error-path examples

For any API that can fail in normal operation, show one failure: what the error object/exception/status looks like and the minimal correct response to it — using the error types the code actually raises (verify the raise site). Happy-path-only documentation produces catch-all error swallowing downstream, the exact failure clean-code-guard exists to stop.

Language and environment tags

• Fenced blocks carry the correct language tag — broken highlighting is a trust signal readers notice.
• State the environment when it changes behavior: shell prompts ($ vs #), OS-specific paths, version-gated syntax.

Sample drift

Samples drift faster than prose because nobody re-runs them. On any code change touching a documented API, grep the docs for the old symbol (SKILL.md Rule 6) — samples are where the stale hits hide. Projects with executable-docs tooling (doctest and kin): prefer it; this skill's manual verification is the floor, not the ceiling.