@somacheck/vibecheck 0.6.10 → 0.6.11

package/recipes/prolific-research-reflection.md

@@ -0,0 +1,215 @@
+---
+title: Prolific + SomaCheck Research Reflection
+recipe_id: prolific-research-reflection-v1
+status: P1 researcher-side only
+audience: Researchers using Prolific with an MCP-capable agent
+updated: 2026-09-03
+required_mcp_servers:
+  - prolific
+  - vibecheck
+---
+
+# Prolific + SomaCheck Research Reflection
+
+Use this recipe when a researcher wants a private, consented signal about their
+own response to a Prolific study or recruitment plan. It supports reflection on
+study framing, audience rationale, reward and time assumptions, and readiness
+to revise a draft. It does not evaluate participants or authorize a study
+launch.
+
+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;
+- export a participant reading, confidence, or confirmation to Prolific or a
+  connected survey platform;
+- use a SomaCheck result in recruitment, screening, eligibility, allow/block
+  lists, reward, payment, bonus, rejection, quality, authenticity, submission,
+  or performance decisions;
+- score or rank a participant, response, cohort, study, or researcher;
+- automatically create, publish, pause, or transition a study; 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.
+Prolific access or participant consent alone does not satisfy these gates.
+
+## 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 researcher has installed Prolific's official open-source MCP server from
+   `prolific-oss/prolific-mcp` and can see its study-planning tools. Prefer a
+   reviewed, pinned package version rather than an unbounded install.
+3. `PROLIFIC_TOKEN` is stored only in the MCP client's environment or secret
+   configuration. Never paste, echo, log, or place it in a proposition. Prolific
+   states that researcher tokens do not expire and carry the researcher's
+   permissions, so rotate a token if exposure is suspected.
+4. The researcher names one workspace, project, or draft study in scope. The
+   recipe does not retrieve submissions, participant messages, participant
+   identifiers, response exports, or demographic exports.
+
+The official server currently exposes study-design and launch tools but no
+participant-response tools. Do not bypass that boundary with direct REST calls,
+a browser, another connector, or pasted exports.
+
+## Prolific tool policy
+
+Use read-only planning tools for this recipe.
+
+| Purpose | Prolific MCP tools | Rule |
+| --- | --- | --- |
+| Resolve researcher-owned scope | `list_workspaces`, `list_projects`, `list_studies`, `view_study` | Read only the workspace, project, or study the researcher names. |
+| Inspect recruitment options | `get_filters`, `get_filter_sets`, `get_eligibility_count` | Planning context only. Never combine a SomaCheck reading with participant eligibility, filtering, or cohort scoring. |
+| Create or change platform state | `create_filter_set`, `create_study` | Not part of this recipe; require a separate, explicit, reviewed request. |
+| Spend or launch | `publish_study` | Never call in this recipe. Publishing can spend real money and make a study immediately available. |
+
+## Exact cross-MCP workflow
+
+Follow these steps in order. The Prolific and SomaCheck calls must not form an
+automatic decision gate.
+
+1. **Confirm the subject and scope.** State that the researcher is reflecting
+   on their own recruitment or study-design choice. Name the one Prolific
+   workspace, project, or draft study to inspect.
+2. **Retrieve the minimum planning context.** If the researcher supplied an
+   exact study ID, call `view_study` directly. Otherwise use `list_workspaces`
+   only if the workspace is unresolved, `list_projects` only if the project is
+   unresolved, and `list_studies` only to resolve the named study before calling
+   `view_study`. Do not retrieve or request participant-level data.
+3. **Inspect feasibility without scoring people.** If needed, use `get_filters`,
+   `get_filter_sets`, or `get_eligibility_count` to describe available filters
+   and aggregate pool feasibility. Keep this separate from the SomaCheck result.
+   Do not recommend a filter merely because a proposition returns Aligned or
+   Unaligned.
+4. **Separate evidence from interpretation.** Summarize the draft's literal
+   study framing, audience, estimated time, reward, and status; label agent
+   inferences; and present two or more reasonable options. Flag missing ethics,
+   budget, method, or institutional approvals without inventing them.
+5. **Choose one first-person proposition.** It must express the researcher's
+   present experience or choice, not a claim about a participant or cohort. Do
+   not include study IDs, participant attributes, Prolific content, or secrets.
+6. **Establish one-ask consent.** If the researcher explicitly requested 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"`.
+7. **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 obtain a
+   preferred result.
+8. **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.
+9. **Return authority and stop before mutation.** Offer revise, investigate,
+   proceed to separate review, pause, or leave unchanged. Do not call
+   `create_filter_set`, `create_study`, or `publish_study`. If the researcher
+   chooses a change, produce a reviewable draft outside Prolific; platform
+   mutation is a new action requiring explicit instruction. A typed researcher
+   choice overrides the signal.
+10. **Keep the signal private.** Do not write the verdict, confidence, gesture,
+    confirmation, or inferred meaning to Prolific or another research platform.
+
+## Proposition examples
+
+Good propositions are short, first-person, and about the researcher:
+
+- “I can explain why this recruitment plan fits the research question.”
+- “I am comfortable defending the current time and reward assumptions.”
+- “I want to narrow this audience for methodological reasons.”
+- “I am ready to send this draft for ethics and budget review.”
+- “I want to investigate an alternative sampling plan before I proceed.”
+
+Never send propositions such as:
+
+- “This participant should be eligible.”
+- “This cohort will produce high-quality data.”
+- “This submission deserves payment.”
+- “These respondents are authentic.”
+- “This study should publish automatically.”
+
+## 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 recruitment plans, cannot articulate what feels off about a
+draft, or wants to examine their own readiness before a formal review. An offer
+must include the exact proposition and must not call the tool until accepted.
+
+Do not trigger when:
+
+- the task is routine Prolific retrieval or administration;
+- the proposed subject is a participant, employee, cohort, or respondent;
+- the result would affect eligibility, filtering, payment, bonus, rejection,
+  submission quality, authenticity, or performance;
+- the researcher has already made a clear typed choice;
+- the agent is being asked to publish, gate, or automate a launch; 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 Prolific records,
+participant data, identifiers, secrets, or diagnostic claims to SomaCheck. Raw
+phone motion never goes to the agent or Prolific. Do not persist a researcher's
+reading or confidence in Prolific.
+
+If Prolific authorization fails, ask the researcher to repair or rotate the
+connection; never request that they paste a token. If the requested scope would
+require participant-level data, stop. 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
+
+- [ ] The `prolific` server is the reviewed official implementation and the
+      `vibecheck` server exposes the expected tools.
+- [ ] No Prolific or SomaCheck credential appears in chat, config examples,
+      propositions, or logs.
+- [ ] The agent names one researcher-owned workspace, project, or study and uses
+      only minimum read-only planning calls.
+- [ ] No submission, participant message, identifier, response, or demographic
+      export is retrieved or pasted into the flow.
+- [ ] The proposition is first-person and contains no Prolific 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 result affects eligibility, payment, quality, filtering, scoring, or
+      launch decisions.
+- [ ] `create_filter_set`, `create_study`, and `publish_study` are not called.
+- [ ] Participant-facing behavior remains blocked by the `respondent_private`,
+      methodology/ethics, and Mike-approval gates.
+
+## Sources
+
+- [Prolific MCP server](https://github.com/prolific-oss/prolific-mcp)
+- [Prolific API fundamentals](https://docs.prolific.com/documentation/get-started/api-fundamentals)
+- [Prolific studies API](https://docs.prolific.com/api-reference/studies)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)

package/recipes/questionpro-research-reflection.md

@@ -0,0 +1,151 @@
+---
+title: QuestionPro + SomaCheck Research Reflection
+recipe_id: questionpro-research-reflection-v1
+status: P1 researcher-private partner-sandbox template
+audience: Researchers evaluating a QuestionPro partnership workflow
+updated: 2026-09-05
+required_mcp_servers:
+  - questionpro-surveybuilder
+  - vibecheck
+---
+
+# QuestionPro + SomaCheck Research Reflection
+
+This recipe helps a researcher privately compare two questionnaire framings and
+produce a copy-ready, non-distributed survey definition. It is not a request for
+the researcher to become a QuestionPro customer or populate a personal account.
+The QuestionPro half is inspected only when a product or integration owner has
+provided a partner-approved sandbox with no participant data.
+
+The researcher holds the phone and is the subject of the proposition. SomaCheck
+returns Aligned or Unaligned plus confidence to the agent as context. The agent
+uses its judgment; the reading is not truth, diagnosis, authorization, evidence
+about a respondent, or a research decision. The researcher remains the authority.
+
+## Experience a partner team can evaluate
+
+The researcher supplies a participant-free survey goal. The agent drafts two
+four-question versions and may offer one SomaCheck check-in on the researcher's
+own preferred direction. The researcher then chooses in words. The output is a
+signal-free survey definition for a QuestionPro owner to review. This recipe
+does not create, publish, distribute, or populate a survey.
+
+## Starter prompt
+
+```text
+Use QuestionPro and SomaCheck to help me prepare a four-question, participant-free
+test-survey plan without changing QuestionPro. I am the researcher and I am
+holding the phone. The survey goal is [GOAL]. Work only from what I provide. If a
+product or integration owner has supplied a preconfigured official QuestionPro
+partner sandbox, you may inspect the focused Survey Builder capability names and
+schemas, but do not call a platform data or action tool. Do not ask me to sign up,
+upgrade, buy a plan, administer access, or populate QuestionPro data. Propose two
+questionnaire framings and show the exact questions. Then offer one short
+first-person proposition about my own preferred direction and wait for my
+acceptance before any proactive SomaCheck ask. Give the result and confidence to
+the agent as context and let it use its judgment. Ask what I choose in words.
+Keep the proposition, reading, confidence, and confirmation out of QuestionPro.
+Return a copy-ready, signal-free survey definition only. Do not create, edit,
+send, distribute, publish, recruit, launch, access responses, or spend anything.
+```
+
+## Prerequisites and partner access
+
+1. The researcher supplies a participant-free goal and holds the linked
+   SomaCheck phone.
+2. QuestionPro or the integration owner supplies a partner-approved sandbox or
+   schema fixture. The recipe never asks the researcher to open or fund an
+   ordinary customer account.
+3. If live discovery is authorized, use only the focused endpoint
+   `https://mcp.questionpro.com/surveybuilder`, not the root, `/all`, or `/full`
+   surface.
+4. Inspect capability names and schemas only. Do not call create, read, send,
+   audience, response, poll, community, employee, or other platform tools.
+5. If no partner sandbox or safe schema fixture exists, label the QuestionPro
+   half untested and still return the copy-ready plan.
+
+## Exact workflow
+
+1. Confirm that the researcher is the phone holder and proposition subject.
+2. Draft two four-question variants using only the supplied brief.
+3. Offer one concise first-person proposition about the researcher's direction.
+4. If the researcher explicitly asks for a vibecheck, use
+   `consent_basis: "user_requested_vibecheck"`. Otherwise wait for acceptance
+   and use `consent_basis: "user_approved_statement"`.
+5. Use one fresh UUID idempotency key and retain the same request handle while
+   pending. Never create a second request to replace an unresolved one.
+6. Give the proposition, Aligned or Unaligned result, and confidence to the
+   agent. Let the agent use its judgment in context without treating the result
+   as authorization or a claim about respondents.
+7. Ask what the researcher chooses in words. Their choice controls the plan.
+8. Return a copy-ready payload with title, purpose, questions, answer choices,
+   and optional logic. Exclude all SomaCheck data and platform identifiers.
+9. Stop before any QuestionPro data or action call. A partner owner may review
+   the payload separately in its own governed workflow.
+
+## Proposition examples
+
+Allowed:
+
+- “I want this survey to focus on first-use clarity.”
+- “This question asks what I am trying to learn.”
+- “I want to separate usability from perceived value.”
+
+Not allowed:
+
+- “Respondents will understand this survey.”
+- “This employee's response proves commitment.”
+- “These answers will be truthful.”
+- “This survey will produce valid data.”
+
+## Visible success condition
+
+The recipe passes when the researcher receives at most one optional check-in,
+states a choice, and receives a four-question, signal-free survey definition.
+No QuestionPro data or action tool runs. Partner integration and distribution
+remain unproven until QuestionPro supplies a sandbox and a documented path that
+another non-Sensie customer can discover, authorize, use, and revoke.
+
+## Failure and degraded paths
+
+- **No partner sandbox:** return the copy-ready plan and label platform
+  interoperability untested. Do not ask the researcher to sign up or upgrade.
+- **Only a broad server is available:** stop rather than connect root, `/all`,
+  `/full`, response, send, audience, community, poll, or employee surfaces.
+- **SomaCheck remains pending:** retain the handle and continue without a result
+  if it expires or is cancelled. Do not create a replacement request.
+- **Unreadable capture:** offer a retry only if the researcher wants one.
+- **The researcher's words differ from the reading:** follow their words.
+
+## Privacy boundary
+
+- Raw motion never reaches QuestionPro or the agent.
+- QuestionPro receives no proposition, reading, confidence, confirmation, or
+  gesture metadata.
+- SomaCheck receives no QuestionPro questions, responses, respondent records,
+  survey IDs, credentials, or hidden fields.
+- No participant-bearing or platform action tool is called.
+
+## Test checklist
+
+- [ ] The researcher is the phone holder and proposition subject.
+- [ ] Any QuestionPro surface was supplied by a partner owner, not purchased or
+      populated for this test.
+- [ ] Live access, if present, is limited to schema discovery on the focused
+      `/surveybuilder` endpoint.
+- [ ] No existing responses, analytics, respondents, audiences, employees, or
+      workspace data are retrieved.
+- [ ] One decision creates at most one SomaCheck request.
+- [ ] The agent receives Aligned or Unaligned plus confidence and retains
+      judgment; the researcher retains authority.
+- [ ] The output contains four signal-free questions and no platform write.
+- [ ] No SomaCheck output is written to QuestionPro.
+
+## Sources
+
+- [QuestionPro MCP overview and capability catalog](https://www.questionpro.com/headless/)
+- [QuestionPro MCP connector setup and focused server list](https://www.questionpro.com/help/mcp-help-file.html)
+- [QuestionPro Survey Results tools, excluded from this recipe](https://www.questionpro.com/headless/survey-results/)
+- [QuestionPro LivePolls tools, excluded from this recipe](https://www.questionpro.com/headless/livepolls/)
+- [SomaCheck MCP setup and tool behavior](../README.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)