u/Main-Philosopher-474

Following up on my earlier thread about AI agents + docs drift. A few

of you (shoutout u/Interstellar_031720) pushed me toward a sharper idea:

instead of "keep docs synced," produce a **drift report** that catches

broken setup/onboarding paths before users hit them.

So I hand-made one against a real repo — no tool, no scanner, just to

test if the *output* is actually useful. Here it is:

───────────────────────────────

DRIFT REPORT — https://www.npmjs.com/package/@kubernetes/client-node (v1.4.0)

Repo: github.com/kubernetes-client/javascript · Issue #2908

Path: calling listNamespacedCustomObject() from the API reference

───────────────────────────────

WHAT BREAKS

A developer following the official API reference writes positional

arguments. The shipped package requires a single options object.

Result: runtime failure on first real call.

THE CONFLICT

- Docs say (positional):

listNamespacedCustomObject(group, version, namespace, plural, ...)

→ kubernetes-client.github.io/javascript/classes/CustomObjectsApi.html

- Package actually requires (options object):

listNamespacedCustomObject({ group, version, namespace, plural, ... })

→ the exported CustomObjectsApi in ObjectParamAPI.d.ts

ROOT CAUSE (deeper than "stale docs")

The docs generator (typedoc src/gen, entryPointStrategy: expand)

renders the INTERNAL positional class, not the exported object-based

class consumers actually get via the ObjectCustomObjectsApi →

CustomObjectsApi alias. The correct class's doc page even 404s.

→ This stays wrong even after the currently-blocked docs rebuild runs.

SEVERITY: 🔴 Blocks first success — new user hits a type/runtime

error before their first working call.

USER-IMPACT EVIDENCE: ⚠️ Inferred, not documented. I searched and

could NOT find a user report tying a runtime error to this exact

mismatch. Consistent with silent-failure (users get a confusing

error, don't file it as a docs bug) — but I won't claim proof I

don't have.

LIKELY OWNER: SDK maintainers / DevRel (docs-generation entry point)

SMALLEST FIX: Point the docs generator at the public API surface

(src/index.ts exports) so the exported class is documented. Fixes

this method + all siblings with the same alias in one change.

───────────────────────────────

Honest question for people who own docs/DevRel/onboarding at a

devtools company:

1. Does this artifact actually clear the bar of "useful," or is it

just a fancy way of saying "your docs are stale"?

2. If a tool surfaced 2-3 of these per month BEFORE your users hit

them — who would own that, and would it be worth budget?

Not selling anything — genuinely trying to learn if the output is

valuable before I build the thing that generates it.

Following up on my earlier thread about AI agents + docs drift. A few

of you (shoutout u/Interstellar_031720) pushed me toward a sharper idea:

instead of "keep docs synced," produce a **drift report** that catches

broken setup/onboarding paths before users hit them.

So I hand-made one against a real repo — no tool, no scanner, just to

test if the *output* is actually useful. Here it is:

───────────────────────────────

DRIFT REPORT — https://www.npmjs.com/package/@kubernetes/client-node (v1.4.0)

Repo: github.com/kubernetes-client/javascript · Issue #2908

Path: calling listNamespacedCustomObject() from the API reference

───────────────────────────────

WHAT BREAKS

A developer following the official API reference writes positional

arguments. The shipped package requires a single options object.

Result: runtime failure on first real call.

THE CONFLICT

- Docs say (positional):

listNamespacedCustomObject(group, version, namespace, plural, ...)

→ kubernetes-client.github.io/javascript/classes/CustomObjectsApi.html

- Package actually requires (options object):

listNamespacedCustomObject({ group, version, namespace, plural, ... })

→ the exported CustomObjectsApi in ObjectParamAPI.d.ts

ROOT CAUSE (deeper than "stale docs")

The docs generator (typedoc src/gen, entryPointStrategy: expand)

renders the INTERNAL positional class, not the exported object-based

class consumers actually get via the ObjectCustomObjectsApi →

CustomObjectsApi alias. The correct class's doc page even 404s.

→ This stays wrong even after the currently-blocked docs rebuild runs.

SEVERITY: 🔴 Blocks first success — new user hits a type/runtime

error before their first working call.

USER-IMPACT EVIDENCE: ⚠️ Inferred, not documented. I searched and

could NOT find a user report tying a runtime error to this exact

mismatch. Consistent with silent-failure (users get a confusing

error, don't file it as a docs bug) — but I won't claim proof I

don't have.

LIKELY OWNER: SDK maintainers / DevRel (docs-generation entry point)

SMALLEST FIX: Point the docs generator at the public API surface

(src/index.ts exports) so the exported class is documented. Fixes

this method + all siblings with the same alias in one change.

───────────────────────────────

Honest question for people who own docs/DevRel/onboarding at a

devtools company:

1. Does this artifact actually clear the bar of "useful," or is it

just a fancy way of saying "your docs are stale"?

2. If a tool surfaced 2-3 of these per month BEFORE your users hit

them — who would own that, and would it be worth budget?

Not selling anything — genuinely trying to learn if the output is

valuable before I build the thing that generates it.

Following up on my earlier thread about AI agents + docs drift. A few

of you (shoutout u/Interstellar_031720) pushed me toward a sharper idea:

instead of "keep docs synced," produce a **drift report** that catches

broken setup/onboarding paths before users hit them.

So I hand-made one against a real repo — no tool, no scanner, just to

test if the *output* is actually useful. Here it is:

───────────────────────────────

DRIFT REPORT — https://www.npmjs.com/package/@kubernetes/client-node (v1.4.0)

Repo: github.com/kubernetes-client/javascript · Issue #2908

Path: calling listNamespacedCustomObject() from the API reference

───────────────────────────────

WHAT BREAKS

A developer following the official API reference writes positional

arguments. The shipped package requires a single options object.

Result: runtime failure on first real call.

THE CONFLICT

- Docs say (positional):

listNamespacedCustomObject(group, version, namespace, plural, ...)

→ kubernetes-client.github.io/javascript/classes/CustomObjectsApi.html

- Package actually requires (options object):

listNamespacedCustomObject({ group, version, namespace, plural, ... })

→ the exported CustomObjectsApi in ObjectParamAPI.d.ts

ROOT CAUSE (deeper than "stale docs")

The docs generator (typedoc src/gen, entryPointStrategy: expand)

renders the INTERNAL positional class, not the exported object-based

class consumers actually get via the ObjectCustomObjectsApi →

CustomObjectsApi alias. The correct class's doc page even 404s.

→ This stays wrong even after the currently-blocked docs rebuild runs.

SEVERITY: 🔴 Blocks first success — new user hits a type/runtime

error before their first working call.

USER-IMPACT EVIDENCE: ⚠️ Inferred, not documented. I searched and

could NOT find a user report tying a runtime error to this exact

mismatch. Consistent with silent-failure (users get a confusing

error, don't file it as a docs bug) — but I won't claim proof I

don't have.

LIKELY OWNER: SDK maintainers / DevRel (docs-generation entry point)

SMALLEST FIX: Point the docs generator at the public API surface

(src/index.ts exports) so the exported class is documented. Fixes

this method + all siblings with the same alias in one change.

───────────────────────────────

Honest question for people who own docs/DevRel/onboarding at a

devtools company:

1. Does this artifact actually clear the bar of "useful," or is it

just a fancy way of saying "your docs are stale"?

2. If a tool surfaced 2-3 of these per month BEFORE your users hit

them — who would own that, and would it be worth budget?

Not selling anything — genuinely trying to learn if the output is

valuable before I build the thing that generates it.

When your AI agent gives wrong code because of outdated context — would you want a dedicated tool for this, or do you expect Cursor/Claude Code to just fix it themselves eventually?

How do you currently handle this? Kindly walk me through it.

When your AI agent gives wrong code because of outdated context — would you want a dedicated tool for this, or do you expect Cursor/Claude Code to just fix it themselves eventually?

How do you currently handle this? Kindly walk me through it. Thank u.