---
name: stimulus-response-polling
description: Use when designing a bounded typed-question study, building respondent profiles, running journeys, querying recorded evidence, or composing follow-on questions at saved respondent contexts.
---

For a new request that starts with material and a question, first use the [study-design skill](../study-design/SKILL.md). It guides the conversation about what to ask and whose perspective matters before the agent constructs a direct request. An agent may choose the response unit, such as page sections, and the typed question. Sheg validates and runs direct requests and journeys, then helps the agent query and reuse their recorded evidence; the agent interprets the machine-readable evidence for the user.

An agent can submit one or more independent typed Choice, Score, or Noul questions over each respondent's same frozen state; a finite authored sequence/graph over exact material and distinct respondent profiles; or a follow-on request that selects saved evaluation/context pairs or evidence criteria. Questions in one group never see sibling answers. A later dependent question belongs in a later journey task or follow-on request that explicitly chooses its answer-history behavior. Each accepted request becomes a durable run with an ID. The run stores its frozen request, logical question groups, reached per-respondent contexts and turn IDs, exposures, per-question typed answers, routes, failures, and physical-attempt accounting. Results vary substantially when the inputs vary: respondent profile, stimulus, question or response, and state such as prior-turn visibility. The cohort supplies respondent-profile variation, so include the distinct perspectives relevant to the decision rather than minimizing cohort size by default. Matching on all four dimensions is duplicate input; another run may show ordinary model variability but adds no substantive coverage. Repeat matching inputs only for an explicit stability or recovery check, and change only dimensions that matter to the user's decision.

| User goal | Read before acting | Tools |
| --- | --- | --- |
| Turn material and a user question into the simplest supported request or journey | [Study design](../study-design/SKILL.md), optionally inspect the request | `run_inspect` |
| Connect a Jev key during installation or after deferring setup | [Secure setup in run and recovery](references/run-and-recovery.md) | Local interactive PowerShell helper, no key-bearing MCP tool |
| Start, discover, query, inspect, cancel, resume, or delete a durable run | [Run and recovery](references/run-and-recovery.md) | `run_start`, `run_list`, `run_get`, `run_query`, `run_cancel`, `run_resume`, `run_delete` |
| Inspect or optimize Sheg-managed storage | [Run and recovery](references/run-and-recovery.md) | `run_storage` |

Before using a tool, establish the question the user wants answered and what decision the result should inform. If they already know the questions, preserve them and put questions that need the same respondent state into one request. If intent is incomplete, work out what answers would satisfy the user, then choose a focused set of typed questions, a response unit, and respondent perspectives that cover meaningful differences relevant to that decision. The agent chooses what counts as a section or “bit”; Sheg does not decompose material or make relevance judgments. Use Choice to select among authored candidates, Score for a position on an ordered rubric, and Noul for a probability. For material-selection Choice, the agent authors exact candidate boundaries and links options to material IDs with `materialOptions`; leave no-fit unlinked. A direct Choice is enough when the user wants to know which candidate they selected. Include `unanswerable` when a respondent may lack enough information. Keep authored text exact and include only the context the user intends respondents to receive.

Choose sequence or graph from the requested topology. A sequence exposes all items in order first, then asks its tasks: `A, B, C, then Q_A, Q_B, Q_C`. It cannot express `A, Q_A, B, Q_B`. Use a graph to interleave questions with material, even on a straight route, or when an answer determines the next turn. On a graph, each respondent receives only material exposed along their reached path; never add unseen sibling-branch material. At each question, the packet includes the exact text of every distinct item exposed so far on that path, in first-exposure order. Re-exposing A after B leaves one copy of A in the packet, while the journey records both exposure events.

Name material and answer history separately. Set `responseHistory: include` on a task to include all earlier typed answers on that path, or `omit` to leave them all out while retaining exposed material. It cannot select individual earlier answers. A follow-on with `context.mode: continue` keeps the source trajectory and appends its completed answer; inspect that packet before promising which answers it will contain. Choose answer visibility from the user's question, independently of sequence, graph, or repeated exposure.

Call `run_inspect` on the exact proposed request when a fit preview would help. Inspection checks the request and context fit; it does not persist a run or call inference. `run_start` performs admission validation itself. If inspection reports invalid or unavailable fit, explain the concrete issue and revise only with the user's intent preserved. Hosted Jev inference requires the user's authorization and a `maxCalls` bound. Laya uses its configured local service and tokenizer checks.

For a direct or follow-on request with several questions, Sheg groups questions per respondent over one identical pre-group state. Inspection reports group/context/question handles and the minimum physical-call count. Jev can send a fitting group in one provider request; when it does not fit, Sheg splits the ordered questions into fitting calls without changing their state. Laya currently sends singleton requests. `maxCalls` counts physical provider attempts across all groups and splits, including retries, rather than answer rows. Never treat answers to sibling questions as if they were visible to one another.

Call `run_start` with a fresh UUID `submissionId` and the exact inspected request. Retain the returned `runId`. If a response is lost, retry with the same submission ID and unchanged request; never invent a new ID for a retry. Call `run_get` status while work is active. Use request and answer views for the frozen input and typed outcomes; use the journey view for respondent-local exposure/response history, reached turn and context IDs, route, and terminal or failure state. `lifecycle.state` says whether execution is active, stopped, or complete; `lifecycle.resume` says whether explicit recovery is eligible and, if not, why. Check counts and status before describing completeness. Reads do not start or resume execution. Use `run_resume` only when the user wants eligible stopped work to continue; it retains the original request, ID, and physical-call ceiling, including uncertain calls.

Use `run_query` to find typed answers, route outcomes, material exposure, question, respondent, and evaluation status in a run. Each answer has its own evaluation ID, shares a context ID with its independent siblings, and reports the provider execution evidence for the physical attempt that produced it. The query returns safe failure details, provenance, whole-run `coverage`, and filter-scoped `matchedCoverage`. Use `matchedCoverage` to report which selected-question answers and respondents are present; a failed sibling question does not make an answered selected question incomplete. `sourceComplete` means only that the entire source run reached `completed`. A progressing run returns matches so far; report that more may match after completion and query again when appropriate. A terminal route such as `left-lost-interest` is not evidence that a typed question identified loss of interest. Query the typed answer as well when the user asks why someone left. Call totals measure provider attempts, not the number or diversity of represented study inputs.

The agent decides which evidence answers the user's question. Use the returned exact evaluation/context references, or repeat the same explicit criteria in a follow-on request. A mapped Choice query result contains `selectedMaterial` (`materialId`, exact `text`, author-supplied `sourceId` and `sourceSha256`, and Sheg-computed `textSha256`). Put that `materialId` in follow-on `context.materialIds` to reuse the selected candidate, including one offered but not encountered during a journey. Sheg selects and freezes those source turns; it does not infer relevance or choose what counts as a “bit” of material. Use `continue` only when the new question should see the selected answer; it adds that explicitly selected answer to the new request's trajectory and leaves sibling answers out. `recorded` reuses the original turn without adding its answer to trajectory. `run_get` with `view: "request"` recalls the frozen groups, packets, and source lineage, while `view: "answers"` returns per-question evidence. Provider attempts are not additional respondents. Describe recorded outcomes and denominators, including failed, pending, and unreached evaluations; do not turn simulated responses into claims about human behavior.