claude-code - 💡(How to fix) Fix [Bug] Claude Code Sonnet session: API speculation stated as confirmed fact, primary specs not consulted until forced

 **Root cause: the session never established what the APIs actually do.**

 The whole thing was structurally backwards. The user's question — "why isn't data flowing?" — required knowing two specs cold: what OTEL env vars Claude Code reads, and what
 URL/CONFIG Zoho Analytics' import API accepts. The agent had verified neither. So every diagnostic was a guess dressed as a finding.

 **The five specific failure modes:**

 1. **Stated my speculation as confirmed fact.** I (advisor) said "every push from Catalyst has silently failed with 500." That was a hypothesis. The agent repeated it to the user
 as a verified diagnosis. The smoke-test row in the table was direct contradicting evidence and got ignored. Fault is shared — I should have framed it as a hypothesis, the agent
 should have filtered it through the existing evidence before repeating.

 2. **Invented an explanation when an API returned an unexpected response.** When `analyticsapi.zoho.in/api/v2/...` returned HTML, agent's first reach was "it must only work from
 inside Catalyst's network" — completely made up, no evidence. The actual answer (`/restapi/v2/bulk/...` is the external path, `/api/v2/` is for internal/admin UI calls) was in the
 OAS spec the whole time. This is the failure that cost the most time.

 3. **Did not consult primary sources until forced.** `github.com/zoho/analytics-oas` is a public repo. Fetching it took one subagent call once the user demanded it. The agent could
  have done that fetch in turn 3. Instead it spent ~15 turns guessing URLs and CONFIG formats. The pattern was: try → fail with cryptic error → guess what the error meant → modify
 and retry. Each guess felt like progress; none was.

 4. **Declared the pipeline "fixed" without verifying telemetry was even enabled.** This is the worst one. The `OTEL_EXPORTER_OTLP_PROTOCOL=http/json` fix is necessary but not
 sufficient. The receiver also needs `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_METRICS_EXPORTER=otlp`, `OTEL_LOGS_EXPORTER=otlp` — and the transform code doesn't read `resourceLogs`
 so 21 event types get silently dropped. The agent told the user "new sessions will now flow" without checking that telemetry was actually on or that the receiver could parse what
 would arrive. The user found all three bugs themselves at the end.

 5. **Did the right thing last instead of first.** Building the four reference docs was the correct move — and it took the user explicitly demanding it. Those docs should have been
 the *opening move* the moment the agent realized it didn't know the API. They would have prevented every subsequent guess.

 **The structural fix for sessions like this:**

 When the task involves an unfamiliar or unverified API surface, the first action is *not* "try a call and see what happens." It's "find and read the spec, then write the call."
 That's true even when there's existing code in the repo claiming to call the API — especially then, because broken code is more dangerous than no code (it ships confidence with the
  bug).

 The agent's pattern of "let me try X" → "let me try Y" → "let me try Z" is appropriate for genuinely unknown territory. It's the wrong move when a spec exists and is one fetch
 away. Distinguishing those situations is the skill that was missing here.

[{"error":"McpToolCallError: No MCP tab group exists. Use tabs_context_mcp with createIfEmpty: true first to create one.\n    at wO3 (/$bunfs/root/src/entrypoints/cli.js:4981:63)\n    at B6K (/$bunfs/root/src/entrypoints/cli.js:4981:1409)\n    at processTicksAndRejections (native:7:39)","timestamp":"2026-05-19T01:18:32.556Z"},{"error":"Error: File does not exist. Note: your current working directory is /Users/tejasgadhia/dev-zoho/claude-enterprise-admin.\n    at call (/$bunfs/root/src/entrypoints/cli.js:4954:11529)\n    at processTicksAndRejections (native:7:39)","timestamp":"2026-05-19T01:56:26.819Z"},{"error":"Error: EISDIR: illegal operation on a directory, read '/Users/tejasgadhia/dev-zoho/claude-enterprise-admin'\n    at oYH (/$bunfs/root/src/entrypoints/cli.js:1648:144)\n    at processTicksAndRejections (native:7:39)","timestamp":"2026-05-19T01:57:57.611Z"}]