docs agent wrote api reference from a cached schema, missed the schema hotfix

TL;DR

Invalidate the schema cache and regenerate from the live schema. Add cache invalidation keyed on the schema's version or hash so hotfixes always trigger regeneration. Verify the reference documents the hotfixed fields.

The exact error

api reference generated from stale cached schema

Steps

1. Confirm the staleness Compare the schema the agent used (check its cache metadata) against the current live schema. Success check: You know the cached schema predates the hotfix.

2. Invalidate and regenerate Clear the schema cache and rerun generation against the live schema. Success check: The reference documents the hotfixed fields.

3. Key the cache on the schema Cache schemas by content hash or version, and invalidate whenever the key changes. Success check: Any schema change invalidates the cache automatically.

4. Verify against live Spot-check the generated reference against the live schema's hotfixed areas. Success check: The docs match the current schema.

When to use

• Use when generated API docs miss a recent schema change.
• Use when an agent caches schemas for doc generation.

When not to use

• Not for specs that were wrong at generation time (source problem).
• Not for intentional doc freezes (pinned schema is the requirement).

Why it happens

Caching the schema speeds up generation but decouples the docs from the API's current state. Hotfixes that do not bump a version the cache key watches will never invalidate the cache, so the docs silently describe the pre-hotfix API.

Edge cases

Content-hash keying is the robust invalidation because it catches every change, including hotfixes. The agent should log the schema hash it generated from so staleness is diagnosable.

Provenance

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