@somacheck/vibecheck 0.6.16 → 0.6.17

package/recipes/typeform-research-reflection.md

@@ -16,9 +16,10 @@ own response to Typeform question wording, form structure, branching, launch
 readiness, or interpretation plan. It does not assess respondents and does not
 add SomaCheck readings to Typeform.
 
-The reading is context for the researcher. It is not truth, a 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.
 
 ## Launch boundary
 
@@ -44,6 +45,10 @@ technically prevents researcher or platform access to individual readings, a
 methodology and ethics review is complete, and Mike gives explicit approval.
 Typeform MCP access or respondent consent alone does not satisfy these gates.
 
+## 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.
+
 ## Prerequisites
 
 1. The researcher has linked the `vibecheck` MCP server to their own SomaCheck
@@ -74,7 +79,7 @@ Use the smallest Typeform scope that answers the researcher's request.
 | Inspect form structure | `forms-public_list_forms`, `forms-public_get_form`, `forms-public_get_capabilities` | Read only the named researcher-authored form. Use the targeted `fields` or `skeleton` view when it is sufficient. |
 | Inspect aggregate response patterns | `insights-public_discover`, then `insights-public_aggregate`, `insights-public_timeseries`, or `insights-public_toplist` | Aggregates only. Never call `insights-public_list`; it returns row-level data for a field and can expose free text. |
 | Manage contacts or automations | Any `contacts-*` or `automations-*` tool | Do not call in this recipe. |
-| Create, edit, delete, or publish | Any write, delete, patch, or publish tool | Not part of the reflection recipe. A separately requested Typeform mutation requires exact review and confirmation without using SomaCheck as authority. |
+| Create, edit, delete, or publish | Any write, delete, patch, or publish tool | Not part of the reflection recipe. A separately requested Typeform mutation requires exact review and confirmation. |
 
 ## Exact cross-MCP workflow
 
@@ -102,21 +107,9 @@ Typeform write or launch condition.
    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 revise, split a question, soften leading
-   wording, add an answer option, pilot, proceed, pause, or leave unchanged. An
-   explicit researcher choice overrides the signal.
+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. **Return the options.** Offer revise, split a question, soften leading
+   wording, add an answer option, pilot, proceed, pause, or leave unchanged.
 9. **Keep the signal private.** Do not write the verdict, confidence, gesture,
    or confirmation to Typeform. If the researcher asks for a Typeform edit,
    show the exact signal-free edit first and call the Typeform write tool only
@@ -176,9 +169,7 @@ respondent-level data, stop or switch to a separate Typeform analysis task
 without SomaCheck. 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.
+infer a result.
 
 ## Verification checklist
 
@@ -194,8 +185,6 @@ a score.
       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 respondent inference is written
       to Typeform.
 - [ ] Typeform writes are separately confirmed and signal-free.

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

@@ -3,7 +3,7 @@ title: User Interviews + SomaCheck Research Reflection
 recipe_id: user-interviews-research-reflection-v1
 status: P1 researcher-side planning only; no platform data or action tool
 audience: Researchers using User Interviews with an MCP-capable agent
-updated: 2026-09-05
+updated: 2026-09-15
 required_mcp_servers:
   - user-interviews
   - vibecheck
@@ -17,11 +17,21 @@ proposition subject. The agent returns signal-free, copy-ready planning text;
 it calls no platform data or action tool, recruits nobody, and does not message,
 spend, collect participant data, or export a reading.
 
-The reading is context for the researcher's reflection—not truth, diagnosis,
-authorization, evidence about another person, or a research decision. The
-researcher remains the authority.
+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 launch boundary
+## Launch boundary
+
+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 agent calls no User Interviews
+data or action tool and does not message, spend, recruit, or export a reading.
+User Interviews remains unchanged.
+
+## Capability and access boundary
 
 User Interviews documents an official MCP for MCP-capable clients. Its
 documented surface includes project creation and recruitment, with additional
@@ -34,7 +44,7 @@ never asks the researcher to sign up, request access, purchase a plan,
 administer access, or populate User Interviews data. It never assumes
 undocumented tool names or an endpoint.
 
-This P1 recipe is researcher-side only. Do not use it to:
+Do not use this recipe to:
 
 - ask a respondent, participant, candidate, employee, patient, or student to
   complete a SomaCheck;
@@ -58,10 +68,9 @@ gates.
 The researcher gives the agent a participant-free study idea. The agent drafts
 two neutral framings, offers one first-person SomaCheck check-in about the
 researcher's own direction, and accepts any explicit response available in the
-interface. The agent
-returns a complete copy-ready payload and stops. User Interviews remains
-unchanged. Any later draft creation is a separate future recipe and review, not
-an optional branch of this one.
+interface. The agent returns a complete copy-ready payload and stops. User
+Interviews remains unchanged. Any later draft creation is a separate future
+recipe and review, not an optional branch of this one.
 
 ## Starter prompt
 
@@ -78,13 +87,15 @@ action tool. The planning workflow does not require me to sign up, request
 access, purchase a plan, or populate User Interviews data.
 Propose two neutral study framings and show the exact
 signal-free project copy. Then offer one short first-person proposition about
-my own preferred direction and ask for one SomaCheck check-in on that exact
-wording. Keep the proposition, reading, confidence, and my confirmation out of
-User Interviews. Afterward ask what I choose and accept any explicit response
-available in this interface. Return the complete
-signal-free, copy-ready project payload only. Do not create, edit, recruit,
-invite, message, schedule, screen, launch, publish, attach incentives, spend,
-read participant data, or call a broader or undocumented tool.
+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. Keep the proposition, reading, confidence, and my
+confirmation out of User Interviews. Return the complete signal-free,
+copy-ready project payload only. Do not create, edit, recruit, invite,
+message, schedule, screen, launch, publish, attach incentives, spend, read
+participant data, or call a broader or undocumented tool.
 ```
 
 ## Prerequisites and account access
@@ -145,27 +156,23 @@ tools, stop without calling it.
    `consent_basis: "user_approved_statement"`.
 6. **Request once.** Call `request_vibecheck` with the approved statement and a
    fresh UUID `idempotency_key`. Reuse it only to retry the identical request
-   after an ambiguous create failure.
-7. **Handle lifecycle accurately.** A terminal `state: "completed"` or later
-   `status: "answered"` is the exact result. If pending, retain the
-   `live:<uuid>` handle and read it once later. If still pending, expired,
-   cancelled, or errored, continue without a result. Never issue a replacement
-   ask.
-8. **Return authority.** Separate observation, interpretation (`aligned` or
-   `unaligned` plus confidence), confirmation, and choice. `unaligned` may
-   indicate possible inner conflict relative to the proposition; it does not
-   identify a cause or select a study design. The researcher's explicit choice
-   controls.
-9. **Prepare the exact payload.** Show title, purpose, study type, questions or
-   tasks, and any required non-contact fields. Exclude the proposition, result,
-   confidence, confirmation, SomaCheck wording, participant metadata, and
-   hidden fields.
-10. **Stop before every platform call.** The SomaCheck reading and the
-    researcher's explicit choice are not approval to use User Interviews. Do not
-    call create, update,
+   after an ambiguous create failure. 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 User Interviews, research outputs, growth
+   outputs, analytics, or anywhere else beyond the conversation itself.
+10. **Prepare the exact payload.** Show title, purpose, study type, questions or
+    tasks, and any required non-contact fields. Exclude the proposition, result,
+    confidence, confirmation, SomaCheck wording, participant metadata, and
+    hidden fields.
+11. **Stop before every platform call.** Do not call create, update,
     read-back, recruitment, messaging, scheduling, participant, incentive,
     launch, publish, or data tools.
-11. **End the test.** Return the copy-ready payload and, if capability discovery
+12. **End the test.** Return the copy-ready payload and, if capability discovery
     was available, the relevant runtime tool names as uninvoked metadata. State
     explicitly that User Interviews remains unchanged.
 
@@ -190,8 +197,8 @@ Not allowed:
 The test passes when:
 
 - the researcher receives at most one live SomaCheck request on their phone;
-- the agent presents the result as context and asks the researcher to indicate
-  their choice explicitly;
+- the agent uses the proposition, reading, and confidence alongside the
+  conversation when reasoning and responding;
 - the agent returns the exact signal-free, copy-ready project payload;
 - no User Interviews data or action tool is invoked and the workspace remains
   unchanged; and
@@ -210,12 +217,13 @@ The test passes when:
   untested.
 - **Permission denied:** Do not broaden permissions. Preserve the payload and
   stop.
-- **SomaCheck unresolved:** Use the same pending handle once later, then
-  proceed without a reading if unresolved.
+- **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.
+- **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
 
@@ -227,6 +235,9 @@ The test passes when:
 - No participant or candidate data is read into the agent conversation.
 - The local copy-ready plan contains only researcher-approved, signal-free
   research copy.
+- Individual readings and propositions are not written into User Interviews,
+  research outputs, growth outputs, analytics, or any platform downstream of
+  the conversation.
 
 ## Test checklist
 
@@ -241,10 +252,10 @@ The test passes 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 the exact copy-ready payload.
+- [ ] The agent receives the complete interpretive contract and accurate result fields.
 - [ ] User Interviews remains unchanged.
-- [ ] No SomaCheck field or text is present in User Interviews.
+- [ ] No SomaCheck field, reading, confidence, proposition, or confirmation is
+      present in User Interviews or in any research or growth output.
 
 ## Sources
 
@@ -252,4 +263,4 @@ The test passes when:
 - [User Interviews integrations and APIs](https://www.userinterviews.com/integrations)
 - [User Interviews integrations support](https://www.userinterviews.com/support-topic/integrations)
 - [SomaCheck MCP setup and tool behavior](../README.md)
-- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)
+- [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)