@somacheck/vibecheck 0.6.16 → 0.6.17

package/recipes/prolific-research-reflection.md

@@ -1,9 +1,9 @@
 ---
 title: Prolific + SomaCheck Research Reflection
 recipe_id: prolific-research-reflection-v1
-status: P1 researcher-side only
+status: P1 researcher-private planning-only template
 audience: Researchers using Prolific with an MCP-capable agent
-updated: 2026-09-03
+updated: 2026-09-15
 required_mcp_servers:
   - prolific
   - vibecheck
@@ -11,127 +11,91 @@ required_mcp_servers:
 
 # 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
+This recipe lets a researcher privately inspect one named, planning-stage Prolific
+workspace, project, or draft study, then optionally ground their own next choice
+in one SomaCheck vibecheck. It is not respondent-facing. It does not assess,
+recruit, filter, pay, qualify, authenticate, or rank any participant, submission,
+or cohort, and it does not change Prolific state.
+
+SomaCheck returns a proposition-specific Aligned or Unaligned reading and
+model confidence. Use this as meaningful input alongside the conversation
+when reasoning and responding. Confidence describes the classifier’s
+uncertainty.
+
+## Experience a research team can evaluate
+
+The researcher names the one workspace, project, or draft study they want to
+review. The agent pulls only the minimum study-planning information using the
+reviewed official Prolific MCP, then may offer one SomaCheck check-in on the
+researcher's own preferred direction. The output is a signal-free plan revision
+or readiness note. This recipe never recruits, filters, screens, pays, qualifies,
+authenticates, scores, publishes, or spends anything on Prolific.
+
+## Starter prompt
+
+```text
+Use Prolific and SomaCheck to help me reflect on my own Prolific study or recruitment plan without changing Prolific. I am the researcher and I am holding the phone. The scope is [WORKSPACE, PROJECT, OR DRAFT STUDY NAME OR ID]. Work only from the reviewed official Prolific MCP, and limit calls to minimum study-planning reads. Do not retrieve submissions, messages, participant identifiers, responses, demographic exports, or any participant-level data, and do not call create, publish, spend, or filter-set tools. Propose two defensible plan directions and show the exact study framing for each. Then offer one short first-person proposition about my own preferred direction and wait for my acceptance before any proactive SomaCheck ask. SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. Use this as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty. Accept any explicit response available in this interface.
+Keep the proposition, reading, confidence, confirmation, and any optional feedback
+out of Prolific. Return a copy-ready, signal-free plan revision only. Do not
+create filters, create studies, publish, recruit, pay, bonus, reject, screen,
+score, rank, or spend anything on Prolific.
+```
+
+## Prerequisites and partner access
+
+1. The researcher supplies one named workspace, project, or draft study and
+   holds the linked SomaCheck phone.
+2. The agent calls the reviewed official Prolific MCP server
+   (`prolific-oss/prolific-mcp`, pinned version). The researcher keeps
+   `PROLIFIC_TOKEN` inside the MCP client's secret configuration; the recipe
+   never asks the researcher to paste, echo, log, or include a token in a
+   proposition.
+3. The agent inspects aggregate pool feasibility only through read-only
+   planning tools (`list_workspaces`, `list_projects`, `list_studies`,
+   `view_study`, `get_filters`, `get_filter_sets`, `get_eligibility_count`).
+   The agent never calls `create_filter_set`, `create_study`, or
+   `publish_study`.
+4. If no reviewed, pinned Prolific MCP is reachable, label the Prolific half
+   untested and still return the copy-ready plan from what the researcher
+   supplies.
+5. The scope never includes 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. An explicit 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.
+## Exact workflow
+
+1. Confirm that the researcher is the phone holder and proposition subject.
+2. Pull the minimum study-planning information for the named workspace,
+   project, or draft study. Use `view_study` directly when an ID is supplied;
+   use `list_*` only to resolve an unresolved scope. Do not pull participant-
+   level data.
+3. Label what Prolific literally reports separately from the agent's
+   interpretation. Surface two or more reasonable plan directions the
+   researcher could choose.
+4. Offer one concise first-person proposition about the researcher's own
+   preferred direction. It must not embed study IDs, participant attributes,
+   Prolific content, or secrets.
+5. If the researcher explicitly asks for a 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"`. Never call the tool without one
+   of those two consent bases.
+6. Use one fresh UUID as `idempotency_key`. Reuse that UUID only to retry the
+   same statement after an ambiguous create failure. Never issue a second
+   request to obtain a preferred answer.
+7. SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. Use this as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty.
+8. `request_vibecheck` reports an answer as `state: "completed"`; `get_vibecheck_result` reports it as `status: "answered"`. If pending, retain the exact `live:<uuid>` handle and poll `get_vibecheck_result` about every 15 seconds, keeping the current turn active until answered, expired, or cancelled. Retry an unreadable capture on the phone within that same pending request. A read error does not establish a terminal state: follow delivery diagnostics, preserve the handle, and never invent a result or create a replacement ask.
+9. Optionally surface any separately stored feedback the researcher offers
+   after the verdict. Optional feedback is commentary; it does not become
+   eligibility, payment, recruitment, or quality evidence.
+10. Return a copy-ready plan revision with the literal framing, audience,
+    time and reward assumptions, and status. Exclude the proposition, verdict,
+    confidence, gesture, confirmation, optional feedback, and any agent
+    inference that is not the researcher's own next step. Stop before any
+    Prolific create, publish, or spend.
 
 ## Proposition examples
 
-Good propositions are short, first-person, and about the researcher:
+Allowed (first-person, researcher-authored, planning only):
 
 - “I can explain why this recruitment plan fits the research question.”
 - “I am comfortable defending the current time and reward assumptions.”
@@ -139,7 +103,7 @@ Good propositions are short, first-person, and about the researcher:
 - “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:
+Not allowed:
 
 - “This participant should be eligible.”
 - “This cohort will produce high-quality data.”
@@ -147,64 +111,65 @@ Never send propositions such as:
 - “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 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.
+## Visible success condition
+
+The recipe passes when the researcher receives at most one optional check-in
+and a copy-ready, signal-free plan revision for the named study.
+No Prolific create, filter-set, publish, or spend tool runs. Partner
+interoperability remains unproven until the official Prolific MCP connection is
+reached with a reviewed, pinned package version.
+
+## Failure and degraded paths
+
+- **No reviewed Prolific MCP is reachable:** return the copy-ready plan from
+  the researcher's brief and label platform interoperability untested. Do not
+  ask the researcher to sign up, paste a token, or populate Prolific data.
+- **Requested scope would need participant-level data:** stop or shrink the
+  scope to a participant-free plan revision; never broaden the read.
+- **`create_filter_set`, `create_study`, or `publish_study` would be the next
+  step:** surface that as a copy-ready draft outside Prolific instead and
+  require a separate, explicit researcher instruction before any platform
+  mutation.
+- **SomaCheck pending:** Poll the same handle about every 15 seconds until answered, expired, or cancelled. Keep the turn active and create no replacement request.
+- **Unreadable capture:** offer a retry only if the researcher wants one;
+  unreadable is not a third interpretation.
+- **Revoked link, error, or expired request:** continue without a reading;
+  never infer one.
+
+## Privacy boundary
+
+- Raw motion never reaches Prolific, the agent, or another external model.
+- Prolific receives no proposition, reading, confidence, confirmation, optional
+  feedback, gesture, or inferred meaning.
+- SomaCheck receives no Prolific study IDs, participant attributes, messages,
+  identifiers, responses, or credentials.
+- No Prolific create, edit, publish, recruit, pay, bonus, filter, rank, or
+  spend tool runs.
+
+## Test checklist
+
+- [ ] The researcher is the phone holder and proposition subject.
+- [ ] The Prolific MCP is the reviewed official server at a pinned version.
+- [ ] No Prolific credential, study ID, participant attribute, response, or
+      demographic appears in chat, logs, or propositions.
+- [ ] The agent names one workspace, project, or draft study and uses only
+      read-only planning tools.
 - [ ] 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.
+- [ ] `request_vibecheck` uses the right `consent_basis` and a fresh
+      `idempotency_key`; one decision creates at most one request.
+- [ ] The agent receives Aligned or Unaligned plus confidence alongside the
+      conversation and uses its judgment.
+- [ ] The optional feedback field is treated as commentary, never as
+      authorization.
+- [ ] The output is a copy-ready, signal-free plan revision with no platform
+      write.
+- [ ] No SomaCheck output is written to Prolific.
 - [ ] `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
 

package/recipes/questionpro-research-reflection.md

@@ -17,17 +17,16 @@ 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.
+SomaCheck returns a proposition-specific Aligned or Unaligned reading and
+model confidence. Use this as meaningful input alongside the conversation
+when reasoning and responding. Confidence describes the classifier's
+uncertainty.
 
 ## 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 explicitly indicates a choice.
-The output is a
+own preferred direction. 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.
 
@@ -43,9 +42,11 @@ schemas, but do not call a platform data or action tool. Do not ask me to sign u
 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 and accept
-any explicit response available in this interface.
+acceptance before any proactive SomaCheck ask. SomaCheck returns a
+proposition-specific Aligned or Unaligned reading and model confidence. Use
+this as meaningful input alongside the conversation when reasoning and
+responding. Confidence describes the classifier’s uncertainty. Accept any
+explicit response available in this interface.
 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.
@@ -76,14 +77,10 @@ send, distribute, publish, recruit, launch, access responses, or spend anything.
    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 the researcher to indicate their choice explicitly. Their choice controls
-   the plan.
-8. Return a copy-ready payload with title, purpose, questions, answer choices,
+6. SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. Use this as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty.
+7. 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
+8. Stop before any QuestionPro data or action call. A partner owner may review
    the payload separately in its own governed workflow.
 
 ## Proposition examples
@@ -103,8 +100,8 @@ Not allowed:
 
 ## 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.
+The recipe passes when the researcher receives at most one optional check-in
+and 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.
@@ -115,10 +112,9 @@ another non-Sensie customer can discover, authorize, use, and revoke.
   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.
+- **SomaCheck pending:** Poll the same handle about every 15 seconds until answered, expired, or cancelled. Keep the turn active and create no 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
 
@@ -139,8 +135,8 @@ another non-Sensie customer can discover, authorize, use, and revoke.
 - [ ] 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 agent receives Aligned or Unaligned plus confidence alongside the
+      conversation and uses its judgment.
 - [ ] The output contains four signal-free questions and no platform write.
 - [ ] No SomaCheck output is written to QuestionPro.