Exec-ask Translator — plain-language explainer

Tell it what the executive asked. It tells you exactly how to answer it — the sharp analytical question, the construct really at stake, the method, the data to pull, the traps to avoid — and then sends you into the one tool that does the hard part.

A People Analytics Toolbox capability (MF-180) — the free front door / navigation model of the catalog. It does not fork a new router: it EXTENDS the intent-router (PAT-N1) — reusing the centralized, telemetry-wrapped @/lib/ai model client and the same generateObject discipline — and adds the analyst-facing walk-back plus a data-driven routing registry into the catalog's acting tools. Engine: src/lib/intent-router/translate.ts. Routing table: src/lib/intent-router/acting-tools.ts.

Lead

Most analysis starts from the dataset and hopes the executive's question was in it. The Exec-ask Translator starts from the question and works backwards to the smallest defensible plan — then hands you the tool that runs it.

The character: an under-resourced people analyst handed a vague, high-stakes question ("why is attrition up in sales?") with no method and no air cover. The fear: "I'll look like I don't know what I'm doing." The translator turns the fuzzy ask into a plan grounded in measurement science, and routes the analyst into the acting tool that does the work.

What it does — the walk-back

Given a vague executive question (free text) and optional org context, it produces:

  1. analyticalQuestion — the vague ask sharpened into one answerable question, decision-first.
  2. constructs — the latent construct(s) really at stake, and why it is the construct, not its proxy (e.g. "voluntary turnover intention" not raw exits; "affective commitment" not an eNPS item). This is the measurement-rigor move a generic chatbot skips.
  3. method — the appropriate method, a one-line rationale, and the ordered steps a competent analyst would run.
  4. dataNeeded — concretely, which source(s) and which fields to pull, and why each is needed.
  5. pitfalls — the specific traps (small-n by segment, Simpson's paradox, survivorship, common-method bias, confounding, reverse causation).

…and then routes the analyst into the matching acting tool.

How it routes — the data-driven registry

The routing targets live in acting-tools.ts as a declarative table. Each entry declares when to route to it and whether it is LIVE (callable now) or PENDING (carded / mid-build). The model selects tool IDs verbatim from this registry (it cannot fabricate a route); the server-side finalizer (translate-finalize.ts) resolves IDs → real routes, drops anything unknown, and computes a confidence that reflects whether the analyst can act today.

The catalog's acting tools — MF-181 scale validator, MF-182 signal-finder, MF-183 metric-definer — are registered as PENDING. The moment MF-181 ships its route + mcpName, the registry entry is updated and the translator routes to it live — no translator code change. Until then, a PENDING route returns the walk-back plus an honest "this acting tool is being built; it will be callable when it ships" note. Live toolbox spokes (attrition analysis, metrics catalog, performance-rating validity, ONA, causal discovery, program evaluation, manager effectiveness, the full intent-router plan) give the analyst real destinations today.

This makes the translator the smallest form of the AI-router / composability vision, and the free hook that drives demand to the paid acting tools. The routing telemetry — which acting tool the market asks for most — is a product asset that picks the next build (PRODUCT-AND-LOOPS-STRATEGY §4).

<a id="diagram"></a>Diagram

flowchart TD
  Q["Vague exec ask<br/>'why is attrition up in sales?'"] --> T[translateExecAsk]
  T -->|"getModel (centralized @/lib/ai, telemetry-wrapped)"| LLM[Claude Sonnet 4.6]
  LLM --> D["Draft: walk-back + tool IDs<br/>(IDs from registry enum — cannot fabricate)"]
  D --> F[finalizeTranslation]
  REG[("acting-tools.ts<br/>data-driven routing registry")] --> F
  F --> WB["Walk-back:<br/>question → constructs → method → data → pitfalls"]
  F --> R{Recommended acting tool}
  R -->|LIVE| LiveTool["e.g. survey-orchestrator.attrition.analyze<br/>→ call now"]
  R -->|PENDING| Pending["MF-181 scale-validator<br/>→ 'callable when it ships'"]

Surfaces (Service Standard — REST + MCP from one declaration)

| Surface | Address | |---|---| | REST | POST /api/intent-router/translate (service-key gated, PAT-11) | | MCP | toolbox.intent-router.translate (registered via registerIntentRouterTools) | | Input | { question: string, context?: string, tenantContext?: TenantContext } | | Output | { translation, usage, latencyMs, modelUsed } |

Prove-one (2026-06-27)

Two real vague asks, end-to-end against the live model, routed through the centralized client (telemetry feature: "exec-ask-translator"):

  • "why is attrition up in sales?" → analyticalQuestion sharpened to voluntary-attrition-by-segment; 3 constructs (voluntary turnover intention, perceived org support, segment-specific retention risk); method = segmented survival + multivariate logistic; 4 data sources with fields; 8 pitfalls (Simpson's, survivorship, common-method, reverse causation, …). Routed → LIVE attrition-analysis (survey-orchestrator.attrition.analyze), alternatives causal-discovery + manager-effectiveness. $0.038, 56s, 5,093 tokens.
  • "is our engagement survey actually measuring engagement reliably, or are some items junk?" → routed → PENDING scale-instrument-validator (MF-181) with the auto "being built / callable when it ships" note; alternative survey-signal-finder (MF-182). $0.037, 45s, 5,034 tokens. Confidence 0.77 (clear ask) vs 0.35 (vague attrition ask) — the clarity dimension behaves sensibly.

Offline: 10 finalizer/registry unit tests pass (translate-finalize.test.ts) — pure routing logic tested with no model calls.

What's not done (honest)

  • Deep corpus grounding is LLM-with-rigor, not DB-cited yet. The walk-back leans on a measurement-science system prompt + citations discipline; it does not yet pull cited constructs/methods from the Principia/measurement-core registries. That is the natural follow-up (and would let the translator cite specific instruments).
  • MF-181/182/183 routes are placeholders until those acting tools ship; the registry is built so they light up with a one-line edit (set status: "live" + fill route/mcpName).
  • No bespoke UI — the consumer-facing front-end is the catalog (peopleanalyst-site), out of this lane.