/ratel-langsmith-integrate — wire LangSmith coverage and dashboards for an agent

Mount LangSmith 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 charts to build on the Monitor and custom dashboards, with concrete configurations). The plan is the deliverable. Do not edit the agent code, and do not call the LangSmith API — the customer builds dashboards by clicking through the LangSmith UI; that is intentional.

This is the LangSmith 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 LangSmith, it routes here to render the plan into concrete LangSmith primitives. Its downstream follow-up, once traces are flowing, is /ratel-langsmith-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 run." That produces run trees that match the code's call graph but tell you nothing about what the agent was trying to do. LangSmith traces are most useful when their structure matches the conceptual structure of a turn:

• Trace (root run) = 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.
• Child run = one step the agent took inside that unit. Sub-agent invocations (chain runs), tool calls (tool runs), model calls (llm runs), retrieval steps (retriever runs). Nest them to reflect delegation, not source-file layout.
• Thread = a set of related traces sharing a thread metadata key (session_id, thread_id, or conversation_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 LangSmith-specific rendering of the vocabulary — which generic concept maps to which run type and metadata key — lives in references/langsmith-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: