@somacheck/vibecheck 0.6.9 → 0.6.11

package/recipes/user-interviews-research-reflection.md

@@ -0,0 +1,253 @@
+---
+title: User Interviews + SomaCheck Research Reflection
+recipe_id: user-interviews-research-reflection-v1
+status: P1 researcher-side planning only; no platform data or action tool
+audience: Researchers using User Interviews with an MCP-capable agent
+updated: 2026-09-05
+required_mcp_servers:
+  - user-interviews
+  - vibecheck
+---
+
+# User Interviews + SomaCheck Research Reflection
+
+This recipe gives a researcher one private SomaCheck check-in while shaping a
+small User Interviews test-project plan. The researcher is the phone holder and
+proposition subject. The agent returns signal-free, copy-ready planning text;
+it calls no platform data or action tool, recruits nobody, and does not message,
+spend, collect participant data, or export a reading.
+
+The reading is context for the researcher's reflection—not truth, diagnosis,
+authorization, evidence about another person, or a research decision. The
+researcher remains the authority.
+
+## Capability and launch boundary
+
+User Interviews documents an official MCP for MCP-capable clients. Its
+documented surface includes project creation and recruitment, with additional
+research-lifecycle capabilities expanding over time. A product or integration
+owner may provide an organization-authorized connection or partner sandbox for
+capability validation. This first recipe may inspect runtime capability names
+and schemas in that preconfigured environment, but it calls no User Interviews
+data or action tool. The planning workflow still works without a connector and
+never asks the researcher to sign up, request access, purchase a plan,
+administer access, or populate User Interviews data. It never assumes
+undocumented tool names or an endpoint.
+
+This P1 recipe is researcher-side only. Do not use it to:
+
+- ask a respondent, participant, candidate, employee, patient, or student to
+  complete a SomaCheck;
+- retrieve submissions, screener answers, participant profiles, identifiers,
+  messages, recordings, transcripts, session data, or other participant data;
+- use a reading for recruitment, targeting, screening, eligibility, quality,
+  authenticity, payment, incentive, scheduling, attendance, ranking,
+  performance, or launch decisions;
+- write a reading, confidence, gesture, confirmation, or hidden score to User
+  Interviews or a connected research tool; or
+- recruit, invite, contact, schedule, launch, publish, or spend money.
+
+Participant-facing use stays blocked until a `respondent_private` architecture
+prevents researcher or platform access to individual readings, methodology and
+ethics review is complete, and Sensie gives explicit privacy/legal approval.
+User Interviews MCP access or participant consent alone does not satisfy these
+gates.
+
+## Experience a researcher can run
+
+The researcher gives the agent a participant-free study idea. The agent drafts
+two neutral framings, offers one first-person SomaCheck check-in about the
+researcher's own direction, and asks what they choose in words. The agent
+returns a complete copy-ready payload and stops. User Interviews remains
+unchanged. Any later draft creation is a separate future recipe and review, not
+an optional branch of this one.
+
+## Starter prompt
+
+```text
+Use User Interviews and SomaCheck to help me prepare one clearly named,
+participant-free test-project plan without changing User Interviews. I am the
+researcher and I am holding the phone. The study idea is: [STUDY IDEA]. Work
+only from what I provide here. Do not retrieve candidates, participants,
+screeners, responses, profiles, identifiers, messages, recordings, transcripts,
+session data, or other workspace data. If a product or integration owner has
+supplied a preconfigured official User Interviews partner sandbox, you may
+inspect its capability names and schemas, but do not call any platform data or
+action tool. The planning workflow does not require me to sign up, request
+access, purchase a plan, or populate User Interviews data.
+Propose two neutral study framings and show the exact
+signal-free project copy. Then offer one short first-person proposition about
+my own preferred direction and ask for one SomaCheck check-in on that exact
+wording. Keep the proposition, reading, confidence, and my confirmation out of
+User Interviews. Afterward ask what I choose in words. Return the complete
+signal-free, copy-ready project payload only. Do not create, edit, recruit,
+invite, message, schedule, screen, launch, publish, attach incentives, spend,
+read participant data, or call a broader or undocumented tool.
+```
+
+## Prerequisites and account access
+
+1. The researcher has linked the `vibecheck` MCP server to their SomaCheck
+   account and can see `request_vibecheck` and `get_vibecheck_result`.
+2. The planning workflow requires no User Interviews account or connector. For
+   partner integration validation, the product or integration owner may
+   provide a preconfigured organization connection or partner sandbox.
+3. When a sandbox is provided, its MCP client authenticates using the access
+   flow User Interviews provides and exposes its current runtime tool schemas.
+   Do not guess an endpoint, install an unreviewed server, or paste a credential
+   into chat.
+4. The preconfigured client permits capability/schema discovery without
+   automatically invoking a data or action tool. Every User Interviews data,
+   creation, recruitment, contact, launch, and spend tool remains denied for
+   this test. The researcher is not responsible for provisioning the sandbox or
+   populating it with data.
+5. Use a conspicuous title such as
+   `SomaCheck demo — <topic> — 2026-09-03 — DO NOT RECRUIT`.
+
+## User Interviews tool policy
+
+User Interviews documents an MCP that can create studies and recruit
+participants, and separately documents Hub and Recruitment APIs. This recipe
+does not invent or rely on names for those surfaces. Discover the connected
+MCP at runtime without invoking a platform data or action capability.
+
+| Purpose | Runtime capability | Rule |
+| --- | --- | --- |
+| Inspect capability names and schemas | MCP capability discovery only | Record names and boundaries without calling a platform data or action tool |
+| Create, edit, read, or verify an artifact | Any project create/update/read tool | Prohibited in this recipe; return copy-ready text only |
+| Private reflection | `request_vibecheck`, optional `get_vibecheck_result` | One decision, one request, one stable pending handle |
+| Recruit or contact | Any recruitment, invite, message, screener, audience, scheduling, or participant-management capability | Prohibited |
+| Human research data | Any submission, response, profile, identifier, transcript, recording, session, or analysis capability | Prohibited |
+| Spend or launch | Any incentive, payment, budget, publish, launch, or distribution capability | Prohibited |
+
+Do not broaden a connection to a root/all-tools endpoint to make this recipe
+work. If the official MCP exposes only recruitment or participant-bearing
+tools, stop without calling it.
+
+## Exact cross-MCP workflow
+
+1. **Confirm subject and scope.** State that the researcher is the phone holder
+   and proposition subject. Name the new test-project title.
+2. **Use only the researcher's brief.** Do not search User Interviews or read
+   any existing project, participant, response, or workspace artifact.
+3. **Draft two options.** Provide two neutral study framings and explain the
+   tradeoff. Label the researcher's supplied facts, agent interpretation, and
+   suggestions separately.
+4. **Choose one proposition.** It must be short, first-person, and about
+   the researcher's own current direction. Do not include participant claims,
+   platform IDs, study records, or secrets.
+5. **Establish one-ask consent.** If the researcher explicitly requested a
+   check-in in the current message, use
+   `consent_basis: "user_requested_vibecheck"`.
+   Otherwise show the exact proposition, wait for acceptance, and use
+   `consent_basis: "user_approved_statement"`.
+6. **Request once.** Call `request_vibecheck` with the approved statement and a
+   fresh UUID `idempotency_key`. Reuse it only to retry the identical request
+   after an ambiguous create failure.
+7. **Handle lifecycle accurately.** A terminal `state: "completed"` or later
+   `status: "answered"` is the exact result. If pending, retain the
+   `live:<uuid>` handle and read it once later. If still pending, expired,
+   cancelled, or errored, continue without a result. Never issue a replacement
+   ask.
+8. **Return authority.** Separate observation, interpretation (`aligned` or
+   `unaligned` plus confidence), confirmation, and choice. `unaligned` may
+   indicate possible inner conflict relative to the proposition; it does not
+   identify a cause or select a study design. The researcher's typed choice
+   controls.
+9. **Prepare the exact payload.** Show title, purpose, study type, questions or
+   tasks, and any required non-contact fields. Exclude the proposition, result,
+   confidence, confirmation, SomaCheck wording, participant metadata, and
+   hidden fields.
+10. **Stop before every platform call.** The SomaCheck reading and the
+    researcher's typed choice are not approval to use User Interviews. Do not
+    call create, update,
+    read-back, recruitment, messaging, scheduling, participant, incentive,
+    launch, publish, or data tools.
+11. **End the test.** Return the copy-ready payload and, if capability discovery
+    was available, the relevant runtime tool names as uninvoked metadata. State
+    explicitly that User Interviews remains unchanged.
+
+## Proposition examples
+
+Allowed:
+
+- “I want this study to focus on initial comprehension.”
+- “I can explain why this research question matters.”
+- “I want to keep discovery separate from evaluation.”
+- “I am ready to save this as a test project for review.”
+
+Not allowed:
+
+- “This participant is a good fit.”
+- “These candidates will answer honestly.”
+- “This response is high quality.”
+- “This project should recruit automatically.”
+
+## Visible success condition
+
+The test passes when:
+
+- the researcher receives at most one live SomaCheck request on their phone;
+- the agent presents the result as context and asks the researcher for their
+  typed choice;
+- the agent returns the exact signal-free, copy-ready project payload;
+- no User Interviews data or action tool is invoked and the workspace remains
+  unchanged; and
+- no recruitment, invitation, message, screener, participant-data,
+  scheduling, incentive, payment, launch, publication, or spend action occurs.
+
+## Failure and degraded paths
+
+- **Partner sandbox absent or MCP access missing:** Continue with the copy-ready
+  planning workflow and label capability discovery untested. Report the missing
+  capability to the product or integration owner; never request a token in chat
+  or ask the researcher to sign up, request access, purchase a plan, administer
+  access, or populate platform data.
+- **Capability discovery absent or schema changes:** Do not guess a tool name or
+  use a broader server. Return the payload and label the connector half
+  untested.
+- **Permission denied:** Do not broaden permissions. Preserve the payload and
+  stop.
+- **SomaCheck unresolved:** Use the same pending handle once later, then
+  proceed without a reading if unresolved.
+- **Unreadable capture:** Offer a retry only if the researcher wants it;
+  unreadable is not a third interpretation.
+- **Researcher disagrees with the reading:** Follow the researcher's typed
+  choice without reconciliation or repetition.
+
+## Privacy boundary
+
+- Raw phone motion never reaches User Interviews or the agent.
+- User Interviews receives no payload at all in this recipe, including no
+  proposition, reading, confidence, confirmation, or gesture metadata.
+- SomaCheck receives no User Interviews project ID, study copy, participant
+  data, transcript, recording, response, or credential.
+- No participant or candidate data is read into the agent conversation.
+- The local copy-ready plan contains only researcher-approved, signal-free
+  research copy.
+
+## Test checklist
+
+- [ ] The researcher is the phone holder and proposition subject.
+- [ ] Any User Interviews capability inspection uses an official,
+      owner-provisioned organization connection or partner sandbox; no
+      undocumented endpoint or unreviewed server is used.
+- [ ] Runtime inspection, if used, is limited to capability names and schemas;
+      no User Interviews data or action tool is invoked.
+- [ ] No participant, candidate, response, screener, transcript, recording,
+      session, message, incentive, recruitment, or launch tool is called.
+- [ ] The proposition is first-person and contains no platform or participant
+      content.
+- [ ] At most one SomaCheck request is created for the choice.
+- [ ] Observation, interpretation, confirmation, and choice remain separate.
+- [ ] The researcher states a choice and receives the exact copy-ready payload.
+- [ ] User Interviews remains unchanged.
+- [ ] No SomaCheck field or text is present in User Interviews.
+
+## Sources
+
+- [User Interviews MCP support article](https://www.userinterviews.com/support/user-interviews-mcp)
+- [User Interviews integrations and APIs](https://www.userinterviews.com/integrations)
+- [User Interviews integrations support](https://www.userinterviews.com/support-topic/integrations)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)