docs agent failed: stripped security warnings from generated docs

TL;DR

Add a preservation gate: inventory every warning and admonition in the source docs first, then fail the generation run if any are missing from the output. Carry warnings over verbatim, never paraphrased. The agent strips them because summarization-style rewriting treats admonitions as noise, and nothing in a generic "regenerate these docs" instruction says warnings are load-bearing.

The error

docs agent failed: stripped security warnings from generated docs

Steps to fix

1. Confirm the loss: diff one source page against its generated version and list the warning blocks present in source but absent in output.

   • Expected: a concrete list of dropped warnings, e.g. three warning admonitions on the auth page.

2. Build the inventory: scan the source docs for warning markers - RST warning and caution blocks, Markdown blockquote warnings, MDX admonition components, and callout shortcodes - and record each one's heading or first line.

   • Expected: a checklist of every warning in the source tree.

3. Add a post-generation check: every inventoried warning must appear in the output, matched on normalized first line; the run fails with the missing list if any are absent.

   • Expected: the first run after adding the check fails loudly, naming the dropped warnings.

4. Change the writer instruction to carry warnings over verbatim, re-run generation, and confirm the check passes.

   • Expected: green check, warnings present word-for-word in the output.

Use this when

• A docs agent regenerates or migrates pages and security warnings disappear.
• The source docs use admonition blocks, callouts, or warning shortcodes.
• Compliance or safety content must survive doc rewrites.

Not for this skill when

• The warnings were removed deliberately by a human editor (that's an editorial decision, not an agent bug).
• The source never had the warnings (nothing was stripped).
• The issue is warnings rendering incorrectly rather than missing.

Variant phrasings

• docs agent removed warning callouts during rewrite
• generated docs missing security admonitions
• llm rewrite dropped caution blocks from docs
• security notes lost in docs migration

Why it happens

Rewriting models optimize for concise, clean output and deprioritize admonitions: a warning block looks like redundant emphasis next to the paragraph it annotates, so the model folds it in or drops it. A generic "rewrite these docs" instruction never says warnings are mandatory, so the model treats them as style, not content.

Edge cases

• Warnings inside generated API reference (docstrings): inventory those too, not just prose pages.
• Paraphrased warnings: the check must require verbatim carry-over, since a reworded security warning can weaken the meaning.
• Translated docs: run the inventory and check per language.
• Warning text split across a page restructure: match on normalized content, not on page location.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yQ61Ji1Krg0FP1mYVt3zOw