/ratel-langfuse-instrument — plan Langfuse coverage for an agent codebase

Mount Langfuse observability on a customer's codebase the way the Ratel team would: detect the stack, map the agent's mental model, decide one consistent naming/tagging vocabulary, and write a plan the customer can implement file by file. The plan is the deliverable. Do not edit the agent code.

This skill exists because every partner-startup onboarding starts the same way — figure out what they're running, decide what to trace, agree a vocabulary — and we want that conversation to be repeatable instead of ad-hoc. The vocabulary it lands on also becomes the contract for /ratel-langfuse-dashboards and /ratel-langfuse-analyze, which both expect the names/tags/metadata defined here to actually show up in traces.

Philosophy: trace the mental model, not the call graph

A common failure mode is "wrap every function in a span." That produces traces that match the code's call graph but tell you nothing about what the agent was trying to do. Langfuse traces are most useful when their structure matches the conceptual structure of a turn:

Trace = one externally meaningful unit of work (one chat turn, one job, one webhook). Not "one HTTP request" if a request contains multiple agent turns; not "one model call" if a turn contains many.
Observation = one step the agent took inside that unit. Sub-agent invocations, tool calls, model calls, retrieval steps. Nest them to reflect delegation, not source-file layout.
Session = a thread of related traces sharing a session_id. Usually a user conversation, an agent run-id, or a job correlation id.

Two anti-patterns to call out in the plan when you see them in the code:

No session boundary at all — every turn is a fresh trace with no session_id. Multi-turn analysis becomes impossible. The fix is almost always a single line at the agent entry point.
Tool calls captured as untyped events — every tool call lands as a generic event with the tool name in metadata rather than as an observation of type tool with the tool name in name. This blocks the entire native tool-call dashboard surface.