/ratel-langfuse-integrate — wire Langfuse coverage and dashboards for an agent

Mount Langfuse on a customer's codebase the way the Ratel team would, and spec the dashboards that prove it earned its place. One skill, two halves: instrumentation wiring (where tracing belongs, what to name it, how to set it up) and the dashboard build-spec (which boards to build, with concrete widgets). The plan is the deliverable. Do not edit the agent code, and do not call the Langfuse API — the customer builds dashboards by clicking through the Langfuse UI; that is intentional.

This is the Langfuse branch of the observability funnel. The generic /ratel-observability-assessment decides what to capture and which dashboards matter, vendor-neutrally, and detects the vendor. When that vendor is Langfuse, it routes here to render the plan into concrete Langfuse primitives. Its downstream follow-up, once traces are flowing, is /ratel-langfuse-analyze, which reads the live data this plan produces.

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.

The full rationale for this lives once in ../ratel-observability-assessment/references/instrumentation-philosophy.md. The Langfuse-specific rendering of the vocabulary — which generic concept maps to which Langfuse primitive, type, and key — lives in references/langfuse-mapping.md.

Why two groups of dashboards

The dashboard half of this skill always builds two groups, because partner startups want two different stories from the same data: