@somacheck/vibecheck 0.6.16 → 0.6.17

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

@@ -3,7 +3,7 @@ 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
+updated: 2026-09-15
 required_mcp_servers:
   - great-question
   - vibecheck
@@ -18,20 +18,23 @@ 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.
+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.
 
-## Researcher experience
+## Launch boundary
 
-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.
+The phone holder is the researcher. The researcher is the subject of the
+proposition. Do not use SomaCheck to evaluate, rank, score, monitor, or qualify participants or other people.
+
+This P1 recipe is **researcher-side only**. 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 and may
+offer one optional SomaCheck check-in on the researcher's own intended
+direction. The agent returns a signal-free, copy-ready research plan and does
+not create, update, launch, or delete anything in Great Question.
 
 ## Starter prompt
 
@@ -46,15 +49,15 @@ 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 and accept any explicit response available in
-this interface. 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.
+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. Keep the
+proposition, reading, confidence, and any 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
@@ -85,46 +88,47 @@ allowlist.
 | 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
+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.
+owner-supplied artifact. Each Great Question tool call, each SomaCheck call,
+and each SomaCheck result read requires a separate explicit researcher approval
+in the client; the researcher may withhold approval at any step without
+explaining why.
 
 ## 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.
+   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.
+   questions. 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.
+   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. **Return authority.** Ask the researcher to indicate their choice explicitly.
-   Their choice controls what follows and may differ from the signal.
+   failure for the exact same statement. The returned `request_id` and the
+   same idempotency key identify one logical ask; never use the same key for a
+   different statement.
+7. **Handle the real lifecycle.** `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.
+8. **Interpretive contract.** 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.
+9. **Optional feedback.** If the researcher later shares a brief post-reveal
+   reaction, the agent may record it separately. The agent does not write the
+   reading or confidence into Great Question, research outputs, growth
+   outputs, analytics, or anywhere else beyond the conversation itself.
 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.
+    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.
 
@@ -132,25 +136,25 @@ owner-supplied artifact.
 
 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.”
+- "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.”
+- "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;
+- the agent uses Aligned or Unaligned plus confidence as one input alongside
+  the conversation and its judgment;
 - `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
@@ -159,19 +163,21 @@ The end-to-end test passes only when:
 
 ## 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.
+- **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 choice differs from the reading:** Follow their explicit choice
-  without reconciliation or repetition.
+- **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 it. If the
+  researcher declines, continue without a reading. An unreadable capture
+  produces no third reading.
+- **Revocation or expiry mid-flight:** If the researcher revokes the request
+  or the request expires before a reading, stop polling and continue without a
+  reading.
 
 ## Privacy boundary
 
@@ -183,6 +189,9 @@ The end-to-end test passes only when:
 - 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.
+- Individual readings and propositions are not written into Great Question,
+  research outputs, growth outputs, analytics, or any platform downstream of
+  the conversation.
 
 ## Test checklist
 
@@ -196,13 +205,15 @@ The end-to-end test passes only when:
 - [ ] 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.
+- [ ] The agent receives the complete interpretive contract and accurate result fields.
+- [ ] The researcher 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.
+- [ ] No SomaCheck field, reading, confidence, proposition, or confirmation is
+      present in Great Question or in any research or growth output.
 
 ## Sources
 
@@ -210,4 +221,4 @@ The end-to-end test passes only when:
 - [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)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)

package/recipes/maze-research-reflection.md

@@ -3,7 +3,7 @@ title: Maze + SomaCheck Research Reflection
 recipe_id: maze-research-reflection-v1
 status: P1 researcher-side read-only reflection; authenticated Maze MCP capability required
 audience: Researchers using Maze with an MCP-capable agent
-updated: 2026-09-05
+updated: 2026-09-15
 required_mcp_servers:
   - maze
   - vibecheck
@@ -13,7 +13,7 @@ required_mcp_servers:
 
 This recipe gives a Maze researcher one private SomaCheck check-in while
 shaping the researcher's own interpretation plan for one named Maze study.
-The researcher stays the only person who reads, decides, or acts. The recipe
+The recipe
 reads only study metadata or aggregate summary and performs no Maze write.
 
 Maze is a hosted read-only MCP surface (`https://connect.maze.co/mcp`,
@@ -23,9 +23,10 @@ eligibility, so the authenticated MCP capability response is authoritative for
 the connected account. A team reporting `mcpAccess: true` is an eligible live
 connection regardless of its displayed plan label.
 
-The SomaCheck reading is context for the researcher's own interpretation
-plan. It is not truth, diagnosis, authorization, evidence about a Maze
-participant, 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.
 
 ## Capability and access boundary
 
@@ -38,6 +39,8 @@ calling the runtime account/team-details capability and requiring
 or look for a Maze-side MCP toggle. Running this recipe never asks the
 researcher to sign up, upgrade, administer access, or populate Maze data.
 
+Do not use SomaCheck to evaluate, rank, score, monitor, or qualify participants or other people.
+
 This P1 recipe is researcher-side only. Do not use it to:
 
 - ask a Maze participant, respondent, tester, employee, candidate, patient,
@@ -71,10 +74,10 @@ workspace owner. The agent reads only that study's safe metadata (name,
 description, status, mission list, block list, settings) or one aggregate
 summary (mission completion rates, time on task, success-rate aggregate,
 summary counts). It does not open transcripts, response rows, participant
-identifiers, recordings, or free-text fields. The agent offers two defensible
-interpretation framings and one short first-person proposition about the
-researcher's own interpretation plan. After the researcher explicitly indicates a choice,
-the agent stops. There is no Maze write.
+identifiers, recordings, or free-text fields. The agent offers one short
+first-person proposition about the researcher's own interpretation plan,
+waits for explicit acceptance of the exact statement, and then stops. There is no
+Maze write.
 
 ## Starter prompt
 
@@ -89,14 +92,14 @@ summary (mission completion rates, time on task, success-rate aggregates,
 summary counts). Do not retrieve
 transcripts, session recordings, heatmaps, click maps, mission answers,
 participant identifiers, contact fields, demographic exports, free-text
-fields, themes, highlights, or any row-level Maze data. Propose two
-defensible interpretation framings. Then offer one short first-person
-proposition about my own interpretation plan and wait for my acceptance
-before any proactive SomaCheck ask. Treat Aligned or Unaligned plus
-confidence as context, not truth, diagnosis, authorization, or evidence
-about a Maze participant. Ask what I choose and accept any explicit response
+fields, themes, highlights, or any row-level Maze data. Offer one short
+first-person proposition about my own interpretation plan 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, and my confirmation out of Maze. Do
+proposition, reading, confidence, and any confirmation out of Maze. Do
 not create, edit, publish, delete, archive, export, share, tag, comment,
 or write to Maze, a hidden field, a webhook, or any analytics record.
 Continue when the authenticated selected team reports `mcpAccess: true`.
@@ -167,40 +170,25 @@ read, label the Maze half untested and stop.
 4. **Separate evidence from interpretation.** Label what the Maze study
    literally contains, what the agent infers, and what the researcher's
    own judgment must still decide.
-5. **Propose two framings.** Offer two defensible interpretation
-   framings the researcher could choose from, with the tradeoff for each.
-6. **Choose one first-person proposition.** It must be short,
+5. **Choose one first-person proposition.** It must be short,
    first-person, and about the researcher's own interpretation plan. Do not include
    Maze IDs containing PII, participant data, transcript text, contact
    fields, free text, themes, or highlights.
-7. **Establish one-ask consent.** If the researcher explicitly requested a
+6. **Establish one-ask consent.** If the researcher explicitly requested a
    SomaCheck 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"`.
-8. **Request once.** Call `request_vibecheck` with the approved statement
+7. **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.
-9. **Handle the real lifecycle.** A terminal response from
-   `request_vibecheck` uses `state: "completed"`; a later read uses
-   `status: "answered"`. If the initial response is `pending`, retain the
-   returned `live:<uuid>` handle and call `get_vibecheck_result` with
-   it once later. If it is still `pending`, `expired`, `cancelled`, or
-   errors, continue without a result. Never issue a replacement ask.
-10. **Return authority.** Separate 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` may indicate possible inner conflict relative
-    to the proposition; it does not name a cause, choose an interpretation,
-    or justify a research claim.
-11. **Return authority.** Ask the researcher which framing they choose, whether they
-    want a third option, or whether they want to stop. Follow their explicit
-    choice.
-12. **Keep the signal out of Maze.** Do not call any Maze write, mutation,
+8. **Handle the real lifecycle.** `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. **Interpretive contract.** 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.
+10. **Keep the signal out of Maze.** Do not call any Maze write, mutation,
     export, webhook, comment, tag, highlight, insight, analytics, or
     hidden-field tool. Do not store the proposition, reading,
     confidence, confirmation, or gesture metadata in Maze.
-13. **End the test.** Report the exact Maze tool names used and the
+11. **End the test.** Report the exact Maze tool names used and the
     exact metadata or aggregate fields returned, or report the
     copy-ready plan when the Maze half is untested. Do not create,
     edit, publish, delete, archive, export, share, duplicate, or
@@ -242,8 +230,7 @@ The test passes when:
   theme, highlight, insight, automation, or write tool;
 - the researcher receives at most one optional SomaCheck check-in on their phone
   on an exact first-person proposition about their own interpretation plan;
-- the agent presents the result as context, asks the researcher to indicate
-  their choice explicitly, and follows that choice;
+- the agent receives accurate result fields and the complete interpretive contract;
 - the agent makes no Maze write, mutation, export, share, tag,
   comment, or analytics call; and
 - no Maze participant, respondent, or employee data enters the
@@ -268,12 +255,10 @@ The test passes when:
   Report the exact fields received and ask the product or integration owner to
   revoke or limit the scope. Do not use the row-level content in any
   proposition, framing, or interpretation.
-- **SomaCheck unresolved:** Use the same `live:<uuid>` handle once
-  later, then proceed without a reading if still unresolved.
+- **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 it;
   unreadable is not a third interpretation.
-- **Researcher disagrees with the reading:** Follow the researcher's explicit choice
-  without reconciliation or repetition.
+
 
 ## Privacy boundary
 
@@ -307,9 +292,6 @@ The test passes when:
       containing PII, participant data, transcripts, contact fields,
       free-text fields, themes, or highlights.
 - [ ] At most one SomaCheck request is created for the choice.
-- [ ] Observation, interpretation, confirmation, and choice remain
-      separate.
-- [ ] The researcher explicitly indicates a choice and the agent follows it.
 - [ ] The agent makes no Maze mutation, write, export, share, tag,
       comment, or analytics call.
 - [ ] No Maze participant, respondent, or employee data enters the