Powerduck | OpenAPI Studio(@PowerduckLabs):JSDoc says `@returns {Promise<User|null>}` when the function actually throws on a missing user. The agent wrote the comment to match what it thought the code did. The next reader trusts the doc and doesn't handle the throw. Where do you catch doc drift before it becomes a bug?

Powerduck | OpenAPI Studio

@PowerduckLabs

I build Powerduck — local-first OpenAPI studio. Writing about spec drift, AI agents that lie about being done, and docs that drift for months.

Joined December 2025

2 Following 7 Followers

Powerduck | OpenAPI Studio@PowerduckLabs

2026.10.16 23:45

JSDoc says `@returns {Promise<User|null>}` when the function actually throws on a missing user. The agent wrote the comment to match what it thought the code did. The next reader trusts the doc and doesn't handle the throw. Where do you catch doc drift before it becomes a bug?