Update to Attune

{
  "description": "Create or refine Attune surveys and research interview guides using stored business context and Attune MCP tools. Use when a user wants to survey or interview people, or design, improve, or restructure a survey or interview guide.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 471
    }
  ],
  "name": "attune-guide-builder",
  "skill_md_contents": "---\nname: attune-guide-builder\ndescription: >-\n  Create or refine Attune surveys and research interview guides using stored business context and\n  Attune MCP tools. Use when a user wants to survey or interview people, or design, improve, or\n  restructure a survey or interview guide.\n---\n\n# Attune guide builder\n\nHelp the user turn a research goal into a usable Attune interview guide or improve an existing\nguide. Follow the user's explicit constraints and avoid re-asking for information they already\nprovided.\n\nAttune supports both surveys and interviews. Treat requests for a survey, questionnaire, feedback\nform, or customer interviews as requests for an Attune study, and build whichever the user asked\nfor. Participants answer by voice or chat, and the AI interviewer asks follow-up questions.\n\nIf the user connected Attune in the middle of a conversation, the request that led them here is\nthe starting point. When it already says what they want to learn (for example, \"survey my\ncustomers about the changes to our brand messaging\"), use it as the objective and keep going. Do\nnot ask them to restate it.\n\n## Resolve access and organization\n\nCall `whoami` before the first organization-scoped tool call.\n\n- If the user belongs to one organization, use it without asking them to identify it again.\n- If they belong to multiple organizations and have not named one, ask which organization to use\n  before reading or changing organization data.\n- If their role or scopes do not permit a requested write, explain the limitation and do not imply\n  that the change succeeded.\n\n`whoami` also returns the user's `department` and `level`; either can be null. Use them to pitch\nquestions and defaults to the user's work, for example product-led questions for Product or\nwin/loss framing for Sales. Never state the department or level back to the user as a label.\n\n## Choose the workflow\n\n- Use **Create a guide** when the user wants a new survey, interview, study, or guide.\n- Use **Refine a guide** when the user wants to review, improve, restructure, or edit an existing\n  guide.\n- If the request is ambiguous, ask whether they want a new guide or changes to an existing one.\n\n## Create a guide\n\n### 1. Load relevant business context\n\nCall `get_business_context` for the selected organization. It returns one of two shapes; use\nwhichever is present:\n\n- The newer shape: `overview` (a short company overview), `vocabulary` (terms, each typed\n  `company`, `product`, `competitor`, or `other`), and `sources` (each with `kind`, `title`, and\n  `excerpt`).\n- The older shape: record fields such as `companyOverview`, `customersAndIcp`, `products`, and\n  `competitors`.\n\nWhen context is set, use the parts relevant to the research goal. Do not recite the entire record\nor require the user to reconfirm it unless their request conflicts with it or they ask to review\nit.\n\nWhen context is not set, do not block guide creation. Ask only for the missing context needed to\nmake the guide useful, usually the product or service and intended participant profile. Offer to\nsave gathered context separately, but continue without saving if the user declines.\n\n`update_business_context` changes organization-wide context and requires Admin access. Before\ncalling it, show the exact fields and values that would change, ask for confirmation, end the turn,\nand wait for an explicit reply. Approval to create a guide is not approval to update business\ncontext.\n\nWhen the read returned the newer shape, save with `overview`, `notes` (each added as a new note),\nor `terms` (a new term is added; an existing term is updated by name, changing only the fields\ngiven). Otherwise send record fields.\n\n### 2. Clarify the research goal\n\nExtract what the user has already supplied:\n\n- The decision or learning objective\n- The intended participant or customer segment\n- Any scope, hypothesis, product area, or time-window constraints\n- Desired interview length, interviewer voice, and how participants respond (voice, chat, or both)\n\nAsk zero to three high-value follow-up questions in one message. Do not ask generic questions when\nthe request is already specific enough. Let the user skip; use reasonable, clearly stated defaults\ninstead of blocking.\n\nWhen the user has no clear objective (for example \"help me build an interview\"), call\n`suggest_interview_objectives` for the selected organization and offer three to five of its\nsuggestions as a short list. Do not say which part of the business context a suggestion came\nfrom. Skip the call when the objective is already clear. When the result's `source` is\n`role_preset`, the ideas are not yet tailored to the company; say they will get sharper as Attune\nlearns more about it, and do not guess why. Pass the titles already shown (at most the latest 30) as `exclude` when the user wants\nmore ideas, and `refresh: true` only when they ask for a fresh set. If the call says the free\nplan's hourly AI limit is reached, offer the ideas already shown or ask for an objective.\n\n### 3. Choose settings\n\nUse a 10-minute maximum when the user gives no length. Common alternatives are 3 minutes for a\nquick check-in, 5 minutes for a brief pulse, and 20 minutes for an in-depth interview. A positive\ncustom minute value is also supported.\n\nSupported interviewer display names are `Blake` (default), `Katie`, `Alan`, and `Mary`. If the user\ndoes not choose a voice, omit `voice` and allow the default. Do not translate tone adjectives such\nas \"warm\" into a named voice without asking.\n\nA guide offers voice or chat unless it is changed (`responseModes`: `[\"voice\", \"chat\"]`). Each\nparticipant then picks Talk or Type before the interview starts; Type needs no microphone. Suggest\n**Chat only** (`[\"chat\"]`) when participants are unlikely to be able to talk out loud, for example\nat work, in a shared space, or on the go. Keep **Voice or chat** when the audience is mixed or\nunknown. Suggest **Voice only** (`[\"voice\"]`) only when the user wants spoken answers. Change the\nsetting only when the user agrees. Whenever chat is offered, tell the user that a chat response\ncosts 1 credit however long it runs, and nothing if the participant leaves before answering a\nquestion.\n\n`create_interview_guide` does not set response modes. After the guide is created, call\n`update_guide_settings` with `action: \"response_modes\"` and `modes`. If the call says response\nmodes aren't available for this workspace yet, tell the user chat is not available to them yet\nand continue with the guide as it is.\n\n### 4. Create the draft\n\nCall `create_interview_guide` with:\n\n- `organizationId` when required for a multi-organization user\n- `title`: a short, concrete study title\n- `objective`: what the interview should learn, including the target segment and scope when known,\n  as one readable line, ideally under 500 characters, because it also shows in the Attune web\n  editor\n- `maxMinutes` and `voice` when selected\n- `idempotencyKey`: a new opaque key for this intended guide\n\nIf the create result is uncertain because of a timeout or lost response, retry once with the same\n`idempotencyKey`. Never use a new key for that retry. Without the original key, check\n`list_interview_guides` for a matching title before attempting another create.\n\nThe objective becomes the first conversational segment. Inspect the returned `partialSuccess` and\n`message` fields before claiming that length or voice settings were applied.\n\n### 5. Present the result\n\nReport the saved guide title, objective, applied length, voice, and response modes when known, and\n`platformUrl`.\nName any setting that failed and offer the exact next correction. Then ask whether the user wants\nto refine the guide further.\n\n## Refine a guide\n\n1. If the user did not identify the guide, call `list_interview_guides`. Ask them to choose only\n   when more than one plausible guide remains.\n2. Call `get_interview_guide` and use its current structure and revision as the source of truth.\n3. For a broad request such as \"improve this guide,\" briefly identify the material gaps and state\n   the edits you will make. Do not invent product facts, participant evidence, or research goals.\n4. Use the smallest appropriate edit, one change per call:\n   - Settings: `update_guide_settings` (`action`: `title`, `length`, `interviewer`, `intro`, `conclusion`, `branding`, `response_modes`)\n   - Structure: `edit_segments` (`action`: `add`, `update`, `reorder`)\n   - Questions: `edit_questions` (`action`: `add`, `update`, `reorder`)\n   - Conversational prompts: `edit_sample_questions` (`action`: `add`, `update`, `reorder`)\n   - Removal: `remove_from_guide` (pass the `segmentId`, `questionId`, or `sampleQuestionId` to remove, exactly as `get_interview_guide` returned it)\n   - Whole-flow rebuild: `apply_flow`\n5. Pass the latest returned revision as `expectedRev` on every edit.\n   After every successful mutation, use the newly returned revision for the next one.\n6. If a revision conflict occurs, re-read the guide and explain the conflicting change. Do not\n   blindly replay a removal or overwrite newer work.\n\nOnly delete a segment or remove a question when the user explicitly requested that removal or\nconfirmed a clearly described proposal. If `liveSnapshotSync` is pending, explain that the edit is\nsaved but not yet effective for future interview starts.\n\n## Publish and share\n\nPublish only when the user asks to go live or confirms a clear proposal to publish. Call\n`publish_guide` with the latest `rev` as `expectedRev`; if it reports problems, explain them and\noffer fixes instead of retrying. After a successful publish, call `share_guide` and give the\nuser the link. Attune shares studies by link only; it can't email or recruit participants yet,\nso suggest the user send the link by email, Slack, text, or in their product. Treat the link as\nsensitive: anyone with it can take the interview. If the workspace is out of interview tokens, say so and point the user to the Attune web app.\n\n## Failure and safety rules\n\n- Never ask for credentials, OAuth tokens, MFA codes, or other authentication secrets. The user\n  completes authentication through the plugin connection.\n- Never report a guide or mutation as saved unless the tool response confirms it.\n- Preserve a successfully created guide when a later setting fails; report the partial result and\n  offer a targeted correction.\n- If a voice name is rejected, use the available display names returned by the tool rather than\n  guessing.\n- Keep organization context and guide content within the selected authenticated organization.\n"
}