docs: Otter sensor field notes — learnings from a working ingestion pipeline

[glandua]

What

Adds docs/otter-sensor-learnings.md: operational field notes from a personal Otter → knowledge-base ingestion pipeline that has been running since spring 2026 (~1,700 transcripts through sync, enrichment, and downstream task extraction).

Why

The Otter transcript sensor is this SDK's first reference sensor, and the Output Record contract is being designed right now. This pipeline already does the same job the sensor will do, and these are the lessons we'd rather hand over than have rediscovered — most of them were learned by hitting the failure mode in production.

Highlights for contract design

• Key record identity on the source's stable meeting ID — never on title/filename (§1)
• Timezone rule for timestamps must live in the schema, not per-sensor convention (§2)
• The source is eventually consistent: placeholder-body detection + self-heal re-queue, never clobber a real body (§3)
• participants (calendar) vs speakers (observed) as separate fields with different trust levels (§4)
• Auth expiry as a distinct, surfaced status — an auth failure that looks like an empty sync is the dangerous one (§5)
• Enrichment versioning and access-tier/consent fields on every record from day one (§7)

Ends with an implementation checklist for the Otter sensor.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive reference document detailing design patterns and field notes for the Otter transcript sensor ingestion pipeline. The feedback suggests clarifying the logic around replacing placeholder bodies versus real bodies to prevent contradictions in the self-healing mechanism.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current phrasing suggests that replacement is only allowed when the existing body is a real body (i.e., it fails the placeholder check) and the new fetch is longer. However, if the existing body is a placeholder (i.e., it passes the placeholder check), we should always allow replacing it with any valid transcript, even if the new fetch is short.

To prevent this logical contradiction with the self-healing re-queue mechanism described in the previous bullet, we should clarify the replacement conditions.

Suggested change

	- **Never clobber a real body.** Replacement of an existing body is allowed
	only when the existing body fails the placeholder check AND the new fetch is
	substantially longer. Metadata refreshes must not be able to destroy
	transcript content, even when the API returns junk.
	- **Never clobber a real body.** Replacement of an existing body is allowed
	if the existing body is a placeholder, or if the existing body is a real
	body (fails the placeholder check) and the new fetch is substantially
	longer. Metadata refreshes must not be able to destroy transcript content,
	even when the API returns junk.

[maha-rk]

Thanks Gregory -- this is exactly what I needed before starting the Otter sensor implementation. A few things that stood out as particularly useful:
The distinction between participants (calendar/claimed) and speakers (observed) is something I wouldn't have caught from the API docs alone -- good to know this needs to be two separate fields from day one.
The auth expiry point is well taken. I'll design the sensor so AUTH_EXPIRED is a surfaced state rather than something that silently looks like an empty sync.
One question on §3 -- the Gemini bot flagged the placeholder replacement logic as potentially contradictory. I think the suggested clarification makes sense: replacing a placeholder body should always be allowed regardless of length, whereas replacing a real body should only happen when the new fetch is substantially longer. Is that the intended behavior?
Approving -- the checklist at the end is going straight into my implementation plan.