@somacheck/vibecheck 0.6.10 → 0.6.12

package/recipes/dovetail-research-reflection.md

@@ -0,0 +1,204 @@
+---
+title: Dovetail + SomaCheck Research Reflection
+recipe_id: dovetail-research-reflection-v1
+status: P1 researcher-side only
+audience: Researchers using Dovetail with an MCP-capable agent
+updated: 2026-09-03
+required_mcp_servers:
+  - dovetail
+  - vibecheck
+---
+
+# Dovetail + SomaCheck Research Reflection
+
+Use this recipe when a researcher wants a private, consented signal about their
+own response to research work held in Dovetail. It supports reflection on
+question wording, study design, and evidence interpretation. It does not assess
+participants and does not add SomaCheck readings to the research record.
+
+The reading is context for the researcher. It is not truth, a diagnosis,
+authorization, evidence about a participant, or a research decision. The
+researcher remains the authority.
+
+## Launch boundary
+
+This P1 recipe is **researcher-side only**. The person holding the phone and
+receiving the SomaCheck result must be the researcher interacting with the
+agent.
+
+Do not use this recipe to:
+
+- ask a participant or employee to complete a SomaCheck;
+- read, infer, compare, rank, monitor, or gate a participant;
+- export a participant reading, confidence, or confirmation into Dovetail;
+- tag, score, or characterize a transcript, highlight, contact, response, or
+  participant using a SomaCheck result;
+- decide eligibility, compensation, research quality, truthfulness, or whether
+  evidence should be included; or
+- run a live respondent workflow.
+
+Participant-facing use stays blocked until a `respondent_private` architecture
+technically prevents researcher or platform access to individual readings, a
+methodology and ethics review is complete, and Mike gives explicit approval.
+Documentation or workspace access is not approval to cross this boundary.
+
+## Prerequisites
+
+1. The researcher has linked the `vibecheck` MCP server to their own SomaCheck
+   account and can see `request_vibecheck` and `get_vibecheck_result`.
+2. The agent has the Dovetail MCP connection authorized by the researcher. Use
+   Dovetail's hosted endpoint, `https://dovetail.com/api/mcp`, or its documented
+   self-hosted server. Keep API tokens in the MCP client's secret configuration,
+   never in prompts, propositions, comments, or logs.
+3. The researcher names the exact Dovetail doc in scope. Access to a workspace
+   is not consent to search the whole workspace.
+4. The source is allowlisted: a researcher-authored research brief, discussion
+   guide, study plan, or de-identified researcher-authored synthesis.
+
+Never open raw interviews, transcripts, recordings, highlights, channel data,
+contacts, participant identifiers, or participant-authored responses for this
+recipe. If the selected Dovetail artifact mixes allowed planning material with
+participant content, stop and ask for a researcher-authored, de-identified
+summary.
+
+## Dovetail tool policy
+
+Use the smallest read scope that answers the researcher's request.
+
+| Purpose | Dovetail MCP tools | Rule |
+| --- | --- | --- |
+| Locate the named planning artifact | `get_doc`, or `list_docs` only when the researcher supplied a title rather than an ID | Use `get_doc` directly for a researcher-supplied ID. Do not list the workspace or search content when the ID is already known. |
+| Read the planning artifact | `get_doc_content` | Read only an allowlisted researcher-authored doc. |
+| Record a chosen next step | `create_comment` | Optional; call only after the researcher explicitly approves the exact comment. Never include the reading or confidence. |
+| Broad or participant-bearing content | `search_workspace`, project-data, highlight, channel, contact, and file-download tools | Do not call in this recipe. |
+| Other writes | project, folder, doc, data, tag, upload, and import creation tools | Not part of this recipe. Require a separate, explicit user request. |
+
+## Exact cross-MCP workflow
+
+Follow these steps in order. Never call Dovetail and SomaCheck in a way that
+makes the reading an automatic write condition.
+
+1. **Confirm the subject and scope.** State that the researcher is reflecting
+   on their own response. Name the one Dovetail doc to read.
+2. **Retrieve only the approved artifact.** If the researcher supplied a doc ID,
+   resolve it directly with `get_doc`. If they supplied only a title, use
+   `list_docs` to match that exact title, then resolve it with `get_doc`. Read the
+   approved doc with `get_doc_content`. Do not call `search_workspace`. Stop if
+   the doc contains participant-authored or identifying material.
+3. **Separate evidence from interpretation.** Summarize:
+   - what the planning artifact literally says;
+   - what the agent infers may need attention; and
+   - two or more reasonable options the researcher could choose.
+4. **Choose one first-person proposition.** It must express the researcher's
+   present experience or choice, not a claim about participants. Do not place
+   Dovetail content, participant text, names, project identifiers, or secrets in
+   the proposition.
+5. **Establish one-ask consent.** If the researcher explicitly asked for a
+   SomaCheck vibecheck in the current message, call `request_vibecheck` with
+   `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 as `idempotency_key`. Reuse that UUID only to retry the same
+   statement after an ambiguous create failure. Never repeat an ask to seek a
+   preferred result.
+7. **Handle the exact result.** `request_vibecheck` reports a terminal answer as
+   `state: "completed"`; a later `get_vibecheck_result` read reports the same
+   lifecycle point as `status: "answered"`. Treat either as the terminal result
+   and keep four layers distinct: observation (a valid gesture was captured),
+   interpretation (`aligned` or `unaligned` plus model confidence), confirmation
+   (what the researcher says), and choice (what the researcher decides).
+   `unaligned` means possible inner conflict relative to the proposition; it
+   does not identify a cause. If the initial response is `pending`, retain its
+   `live:<uuid>` handle and call `get_vibecheck_result` with that exact handle
+   once later. Do not create a replacement request. If that read is still
+   `pending`, is `expired` or `cancelled`, or errors, continue without a result;
+   do not infer one or start another request.
+8. **Return authority.** Offer the options to revise, investigate, proceed,
+   pause, or leave the artifact unchanged. A typed researcher choice overrides
+   the signal.
+9. **Keep the signal private.** Do not write the verdict, confidence, gesture,
+   or confirmation to Dovetail. If the researcher asks to record a next step,
+   show a signal-free comment first and call `create_comment` only after exact
+   approval.
+
+## Proposition examples
+
+Good propositions are short, first-person, and about the researcher:
+
+- “I can explain why this question asks one thing at a time.”
+- “I want to use this discussion guide in its current form.”
+- “My interpretation separates what participants said from what I inferred.”
+- “I am ready to treat this synthesis as one input to the next design choice.”
+- “I want to investigate a competing explanation before I proceed.”
+
+Never send propositions such as:
+
+- “This participant is telling the truth.”
+- “This transcript is high quality.”
+- “These users support the conclusion.”
+- “This employee is aligned with the company.”
+
+## Trigger and anti-trigger rules
+
+Trigger this recipe when the researcher explicitly asks to reflect with
+SomaCheck. The agent may also **offer** one check when the researcher is choosing
+between defensible question phrasings, sees tension between evidence and an
+interpretation, or says that something in the design feels off but is hard to
+name. An offer must include the exact proposition and must not call the tool
+until accepted.
+
+Do not trigger when:
+
+- the task is ordinary Dovetail retrieval, summarization, tagging, or export;
+- the proposed subject is anyone other than the researcher;
+- the source contains raw or identifiable participant material;
+- the researcher has already made a clear typed choice;
+- the result would determine inclusion, quality, compensation, performance, or
+  another consequential outcome; or
+- a vibecheck was already used for the same decision.
+
+## Consent, privacy, and failure behavior
+
+Linking the MCP servers is setup, not blanket consent. A proactive check always
+requires acceptance of its exact wording. Never send raw conversations,
+Dovetail text, participant data, identifiers, secrets, or diagnostic claims to
+SomaCheck. Raw phone motion never goes to the agent or Dovetail.
+
+If Dovetail authorization fails, ask the researcher to repair the connection;
+never request that they paste a token. If the document's provenance or
+de-identification is unclear, stop before reading it. If SomaCheck reports an
+unreadable capture, request a retry only if the researcher wants one; unreadable
+is not a third interpretation. If the request expires, is cancelled, or errors,
+continue without a reading. Never infer a result. If the result and the
+researcher's words differ, follow the researcher's words and preserve the
+difference rather than reconciling it into a score.
+
+## Verification checklist
+
+- [ ] Both MCP servers expose their expected tools; no credential appears in
+      chat or logs.
+- [ ] The agent names one researcher-authored, participant-free Dovetail doc.
+- [ ] Broad search and disallowed Dovetail data, highlight, channel, contact,
+      and download tools are not called.
+- [ ] The proposition is first-person and contains no Dovetail or participant
+      content.
+- [ ] A proactive ask waits for acceptance; an explicit user request does not
+      add a redundant consent prompt.
+- [ ] One decision creates at most one `request_vibecheck` request and preserves
+      its stable pending handle.
+- [ ] The response distinguishes observation, interpretation, confirmation, and
+      choice.
+- [ ] No reading, confidence, confirmation, or participant inference is written
+      to Dovetail.
+- [ ] Any Dovetail comment contains only the researcher's explicitly approved,
+      signal-free next step.
+- [ ] Participant-facing behavior remains blocked by the `respondent_private`,
+      methodology/ethics, and Mike-approval gates.
+
+## Sources
+
+- [Dovetail MCP server documentation](https://developers.dovetail.com/docs/mcp)
+- [Dovetail API overview](https://docs.dovetail.com/integrations/dovetail-api)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)

package/recipes/great-question-research-reflection.md

@@ -0,0 +1,212 @@
+---
+title: Great Question + SomaCheck Research Reflection
+recipe_id: great-question-research-reflection-v1
+status: P1 researcher-private, read-only partner-sandbox validation
+audience: Researchers using Great Question with an MCP-capable agent
+updated: 2026-09-05
+required_mcp_servers:
+  - great-question
+  - vibecheck
+---
+
+# Great Question + SomaCheck Research Reflection
+
+This recipe gives a researcher one private SomaCheck check-in while reviewing a
+participant-free Great Question test artifact provisioned by a product or
+integration owner. The observable result is a copy-ready research plan informed
+by the artifact's safe structure. Great Question remains unchanged. No
+candidate, participant, transcript, response, session, highlight, or insight is
+read, assessed, or changed.
+
+The researcher interacting with the agent must hold the phone and be the subject
+of the proposition. A reading is context for reflection—not truth, diagnosis,
+authorization, evidence about another person, or a research decision.
+
+## Researcher experience
+
+The product or integration owner supplies a partner sandbox and names one
+participant-free test study. The researcher holds the phone and asks the agent
+to review only that artifact's safe study structure. The agent drafts two
+five-question framings, offers one optional SomaCheck check-in on the
+researcher's own intended direction, receives Aligned or Unaligned plus
+confidence, and uses that context with its judgment before asking what the
+researcher chooses. The agent returns a signal-free, copy-ready research plan.
+It does not create, update, launch, or delete anything in Great Question.
+
+## Starter prompt
+
+```text
+Use Great Question and SomaCheck to help me reflect on a five-question test
+survey plan without changing Great Question. I am the researcher and I am
+holding the phone. The product or integration owner has provisioned a partner
+sandbox and named this participant-free test study: [TEST STUDY NAME OR ID].
+Read only that study's safe title, purpose, and question structure with
+get_survey_study. Do not search or list the workspace, and do not read
+candidates, participants, screeners, responses, sessions, transcripts,
+recordings, highlights, insights, reels, or other workspace data. Propose two
+neutral study framings and show their exact questions. Then offer one short
+first-person proposition about my own preferred framing and wait for my
+acceptance before any proactive SomaCheck ask. Give the agent the Aligned or
+Unaligned result plus confidence as context and let it use that context with
+its judgment. Ask what I choose in words. Keep the proposition, reading,
+confidence, and my confirmation out of Great Question. Return a signal-free,
+copy-ready research plan only. Do not create, update, delete, recruit, invite,
+message, schedule, incentivize, launch, publish, or otherwise write to Great
+Question. Do not ask me to sign up, upgrade, purchase, administer access, or
+populate Great Question data.
+```
+
+## Prerequisites and account access
+
+1. A product or integration owner has provisioned an organization-authorized
+   Great Question connection or partner sandbox at
+   `https://greatquestion.co/api/mcp/v1`, with PII hiding enabled. Running this
+   recipe does not ask the researcher to sign up, upgrade, purchase, administer
+   access, or populate Great Question data.
+2. The owner has supplied one clearly named, participant-free test study and
+   granted read access to that exact artifact through `get_survey_study`.
+3. The client restricts the Great Question half to `get_survey_study` for that
+   owner-supplied ID. No discovery or mutation tool is approved.
+4. The `vibecheck` server is connected to the researcher's SomaCheck account
+   and exposes `request_vibecheck` and `get_vibecheck_result`.
+
+## Great Question tool policy
+
+Great Question exposes a broad read/write MCP. This recipe uses an exact
+allowlist.
+
+| Purpose | Tool | Rule |
+| --- | --- | --- |
+| Read the supplied test artifact | `get_survey_study` | Read only the exact owner-supplied study ID and use only safe title, purpose, and question structure |
+| Private reflection | `request_vibecheck`, optional `get_vibecheck_result` | One decision, one request, stable pending handle |
+| Study discovery | `list_studies`, `search_studies`, `list_survey_studies`, `search_survey_studies` | Not needed; do not call |
+| Candidates and recruitment | All candidate, participant, segment, screener-invitation, scheduling, moderator, and message tools | Prohibited |
+| Human research data | All response, session, transcript, highlight, insight, reel, file, and recording tools | Prohibited |
+| All mutations | Create, update, delete, template-apply, screener, recruitment, and unmoderated/interview tools | Prohibited |
+
+Do not grant “always allow” to Great Question's whole server. Client-side tool
+approval or an allowlist should restrict this test to `get_survey_study` for the
+owner-supplied artifact.
+
+## Exact cross-MCP workflow
+
+1. **Confirm subject and scope.** State that the researcher is the phone holder
+   and proposition subject. Name the owner-supplied test study.
+2. **Read only the supplied artifact.** Call `get_survey_study` only for the
+   exact owner-supplied ID. Use only safe title, purpose, and question structure.
+   Do not search Great Question or retrieve any participant-bearing source.
+3. **Draft two options.** Provide two neutral framings, each with exactly five
+   questions, and explain the tradeoff. Label source facts, agent
+   interpretation, and suggestions separately.
+4. **Choose one proposition.** It must be short, first-person, and about the
+   researcher's own current direction, such as “I want this study to focus on
+   the moment a user decides whether to continue.” It must not include
+   participant claims, Great Question identifiers, or questionnaire text copied
+   from the platform.
+5. **Establish one-ask consent.** If the researcher requested SomaCheck in the
+   current message, use `consent_basis: "user_requested_vibecheck"`. Otherwise
+   display the exact proposition and wait for acceptance before using
+   `consent_basis: "user_approved_statement"`.
+6. **Request once.** Call `request_vibecheck` with the approved statement and a
+   fresh UUID `idempotency_key`. Reuse that key only after an ambiguous request
+   failure for the exact same statement.
+7. **Handle lifecycle accurately.** `request_vibecheck` reports a terminal
+   answer as `state: "completed"`; a later `get_vibecheck_result` reports it as
+   `status: "answered"`. If pending, keep 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. **Use the signal as context.** Give the agent only the proposition, Aligned
+   or Unaligned reading, and confidence. Let it combine that context with the
+   conversation and its judgment. Keep observation, interpretation,
+   confirmation, and choice distinct.
+9. **Ask the researcher to choose in words.** Their typed answer controls what
+   follows and may differ from the signal.
+10. **Return a copy-ready plan.** Include only a test title, goal/purpose,
+    language, and the five questions. Do not attach an incentive, consent form,
+    screener, candidates, recruitment settings, or send settings.
+11. **End without a partner write.** State that Great Question remained
+    unchanged and name the single Great Question read tool called.
+
+## Proposition examples
+
+Allowed:
+
+- “I want this study to focus on initial comprehension.”
+- “I want these two research questions kept separate.”
+- “This wording reflects what I am trying to learn.”
+- “I am ready to save this as a test study.”
+
+Not allowed:
+
+- “This candidate is suitable for the study.”
+- “These participants will answer honestly.”
+- “This response is high quality.”
+- “This study proves users want the feature.”
+
+## Visible success condition
+
+The end-to-end test passes only when:
+
+- the researcher receives at most one optional SomaCheck request on their phone;
+- the agent uses Aligned or Unaligned plus confidence as context and asks the
+  researcher for their choice;
+- `get_survey_study` reads only the exact owner-supplied test artifact;
+- the agent returns a signal-free, copy-ready five-question plan;
+- Great Question remains unchanged; and
+- no candidate, participant, response, transcript, scheduling, messaging,
+  incentive, invitation, or recruitment action occurred.
+
+## Failure and degraded paths
+
+- **MCP access or owner-supplied artifact missing:** Do not ask the researcher to
+  sign up, upgrade, purchase, administer access, or populate Great Question.
+  Return a copy-ready plan from the supplied brief, tell the product or
+  integration owner what is missing, and label the platform half untested.
+- **Permission denied:** Do not broaden workspace permissions. Preserve the
+  copy-ready plan and stop.
+- **Runtime exposes only broad or write tools:** Do not call them. Return the
+  copy-ready plan and label the platform half untested.
+- **SomaCheck unresolved:** Use the same handle once later, then proceed without
+  a reading if unresolved.
+- **Unreadable capture:** Offer a retry only if the researcher wants it.
+- **The researcher's words differ from the reading:** Follow their typed choice
+  without reconciliation or repetition.
+
+## Privacy boundary
+
+- Raw phone motion never reaches Great Question or the agent.
+- Great Question receives no proposition, reading, confidence, confirmation,
+  or gesture metadata.
+- SomaCheck receives no Great Question study ID, questions, participant data,
+  transcript, recording, response, or credential.
+- No participant or candidate data is read into the agent conversation.
+- The copy-ready plan contains only researcher-approved, signal-free research
+  copy and is not written to Great Question.
+
+## Test checklist
+
+- [ ] The researcher is the phone holder and proposition subject.
+- [ ] A product or integration owner provisioned the partner sandbox, exact
+      participant-free test artifact, OAuth connection, and PII hiding.
+- [ ] Client approval is limited to `get_survey_study` for the exact
+      owner-supplied artifact.
+- [ ] No workspace discovery, candidate, participant, response, transcript,
+      other-artifact, scheduling, message, or invitation 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 a copy-ready, signal-free
+      five-question plan.
+- [ ] No create, update, delete, publish, launch, or other partner write occurs.
+- [ ] No incentive, screener, candidate, recruitment, invitation, session, or
+      participant contact exists.
+- [ ] No SomaCheck field or text is present in Great Question.
+
+## Sources
+
+- [Great Question MCP overview](https://greatquestion.co/support/integrations/mcp)
+- [Great Question MCP setup](https://greatquestion.co/support/integrations/mcp-setup)
+- [Great Question MCP tools and data handling](https://greatquestion.co/support/integrations/mcp-available-tools)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)