opencode-metis 0.1.0

package/opencode/skill/user-research/examples/interview-questions.md

@@ -0,0 +1,265 @@
+# Interview Question Bank
+
+## Context
+
+Use these questions as a starting point -- adapt to your product domain and the specific study objectives. Do not read questions verbatim. The goal is conversation, not interrogation. Questions are organized by research phase and purpose.
+
+Pair each question with follow-up probes and silence. The best insight often comes after the participant pauses and keeps going.
+
+---
+
+## Discovery Research
+
+Discovery research explores the problem space before you have a solution. The goal is to understand users' worlds -- their goals, habits, mental models, and the workarounds they have invented to cope with existing problems.
+
+### Opening and Context
+
+These questions establish the participant's context and warm up the conversation. Ask them before anything domain-specific.
+
+- "Walk me through what your typical [day / week] looks like."
+- "What are the most important things you're trying to get done in your role?"
+- "What does success look like for you in [relevant domain]?"
+- "Tell me about the last time you had to deal with [problem area]. What happened?"
+
+**Probes:**
+- "What were you trying to accomplish at that point?"
+- "What was going through your mind when that happened?"
+- "And then what did you do?"
+
+### Understanding Current Behavior
+
+Ask about behavior, not hypothetical behavior. Past events are evidence. Future intentions are speculation.
+
+- "How do you currently handle [task]? Walk me through it step by step."
+- "What tools or workarounds do you use to get that done?"
+- "When was the last time you did that? Can you walk me through exactly what happened?"
+- "Who else is involved when you're doing [task]?"
+- "What do you do when [task] goes wrong?"
+- "What's the most annoying part of how you handle [task] right now?"
+
+**Probes:**
+- "You mentioned [X] -- can you tell me more about that?"
+- "How long does that usually take?"
+- "How often does that happen?"
+- "What do you do if [tool / step] isn't available?"
+
+### Uncovering Pain Points
+
+Let participants articulate frustrations in their own words. Do not suggest the pain point -- have them name it.
+
+- "What's the most frustrating part of your current process?"
+- "What takes longer than it should?"
+- "What do you wish worked differently?"
+- "What do you have to do manually that feels like it shouldn't need to be manual?"
+- "Have you ever just given up on doing [task] a certain way? What happened?"
+- "What's the thing you dread most when [task] comes up?"
+
+**Probes:**
+- "How often does that happen?"
+- "What do you do instead?"
+- "What's the cost of that frustration -- to you, or to your team?"
+- "Has that ever caused a real problem for you? Tell me about it."
+
+### Exploring Goals and Motivation
+
+Understand what users are trying to achieve at the level above the task.
+
+- "Why does [task] matter to you?"
+- "If you could solve one problem related to [domain], what would it be?"
+- "What would make you feel like [domain area] was working really well for you?"
+- "What would need to change for you to feel like your situation improved significantly?"
+- "What do your most successful colleagues do differently from you in this area?"
+
+**Probes:**
+- "Why does that matter?"
+- "What would be different if that were solved?"
+- "What's stopped you from doing that already?"
+
+### Mental Models and Decision-Making
+
+Understanding how participants reason helps you design for their actual model, not yours.
+
+- "How do you decide when to [take an action / use a tool / ask for help]?"
+- "How do you know when something has gone wrong with [task]?"
+- "When you're evaluating [options / vendors / tools], what do you look for?"
+- "How do you know if [task outcome] was successful?"
+- "Who do you trust for advice on [topic]? Why them?"
+
+**Probes:**
+- "What's the most important factor in that decision?"
+- "Has your thinking on that changed over time?"
+- "Walk me through the last time you made that decision."
+
+---
+
+## Usability Research
+
+Usability research evaluates a specific interface or flow. The goal is to observe behavior -- what participants do, where they hesitate, where they fail, and why -- not to collect opinions about the design.
+
+### Task Framing
+
+Frame tasks as scenarios, not instructions. Avoid naming UI elements in the task -- let participants find them.
+
+**Instead of:** "Click the Settings button and change your notification preferences."
+**Use:** "Imagine you want to stop receiving email notifications from this product. Show me how you would do that."
+
+**Instead of:** "Use the filter to find orders from last month."
+**Use:** "You need to find all the orders that came in during October. Take a look around and try to accomplish that."
+
+### Before the Session Starts
+
+Set expectations so participants feel safe failing and think aloud naturally.
+
+- "I want to be clear -- I'm testing the design, not you. There are no wrong answers."
+- "If something is confusing, that's incredibly useful feedback. Please don't assume you're missing something obvious."
+- "As you go through the tasks, please think out loud -- tell me what you're looking at, what you're thinking, what you're trying to do."
+
+### During Task Completion
+
+Prompt thinking aloud without steering the participant toward the solution.
+
+- "What are you thinking right now?"
+- "What do you expect to happen when you do that?"
+- "What are you looking for?"
+- "If you were doing this at home on your own, what would you do next?"
+
+**What not to say:**
+- "You're close." (Evaluative)
+- "Try looking up there." (Directive)
+- "That's the right spot, yes." (Confirming)
+
+### After Each Task
+
+Capture their experience while it is fresh, after they have completed or abandoned the task.
+
+- "How did that go from your perspective?"
+- "Was there a moment where you weren't sure what to do? Tell me about that."
+- "What did you expect to find where you looked first?"
+- "If you had to do that again, what would you do differently?"
+- "What would you call what you just did -- what word comes to mind for that action?"
+
+### After the Session
+
+Gather overall impressions and anything participants held back during tasks.
+
+- "Looking back at everything you saw today -- what stood out most?"
+- "What, if anything, surprised you?"
+- "Is there anything you wish worked differently from what you saw?"
+- "If this were a product you used every day, what would be the first thing you'd want to change?"
+- "Is there anything you were thinking during the session that you didn't say out loud?"
+
+---
+
+## Validation Research
+
+Validation research tests whether a solution -- a concept, prototype, or launched feature -- addresses the problem you intended to solve. The goal is to disconfirm your assumptions, not confirm them.
+
+### Concept Testing
+
+Use these when presenting a concept or early prototype for the first time.
+
+- "Before I show you anything, tell me how you currently handle [problem this addresses]."
+- "Looking at this, what do you think it does?"
+- "Who do you think this is for?"
+- "What problem do you think this is meant to solve?"
+- "If you saw this, what would you expect to happen when you [key action]?"
+
+**Probes:**
+- "What makes you say that?"
+- "Is that what you expected, or did something surprise you?"
+- "What would you need to see to feel confident using this?"
+
+### Relevance and Value
+
+Assess whether the solution addresses a real and important problem for this participant.
+
+- "Does this address a problem you actually have?"
+- "On a scale from not important at all to extremely important -- how much does this matter to you? Why?"
+- "Would you use something like this? In what situation?"
+- "What would you need to believe for this to be worth your time?"
+
+**Probes:**
+- "What would stop you from using it?"
+- "Who else on your team would care about this?"
+- "How does this compare to how you handle it today?"
+
+### Differentiation
+
+Understand how participants position your solution against alternatives.
+
+- "If this existed, how would it fit into your current workflow?"
+- "Is there anything you currently use that does something similar?"
+- "What does this have that [current solution] doesn't?"
+- "What does [current solution] have that this doesn't?"
+- "What would it take for you to switch to something like this?"
+
+### Post-Launch Validation
+
+For features that are already live -- understand adoption and actual impact.
+
+- "Have you used [feature]? Tell me about the last time."
+- "What made you decide to try it?"
+- "What did you expect it to do? Did it do that?"
+- "Has it changed how you [do the related task]? How?"
+- "What would you miss if it disappeared tomorrow?"
+- "Who else on your team has tried it? What did they think?"
+
+---
+
+## Generative Research Starters
+
+These open-ended conversation starters are particularly useful at the start of a research program, when you do not yet have a well-defined problem space and are listening for signals.
+
+- "Tell me about the biggest challenge you're dealing with in [domain] right now."
+- "What's the thing in your work that most often doesn't go the way you need it to?"
+- "If you had an extra two hours a week to dedicate to improving [area of work], what would you work on?"
+- "What's something that used to be a problem that you've actually solved? How?"
+- "If I were starting your job tomorrow, what would you tell me to watch out for?"
+- "What do you know now that you wish you had known when you started in [role]?"
+
+---
+
+## Evaluative Research Starters
+
+These questions are anchored to existing evidence and are particularly useful when you have data (analytics, support tickets, prior research) and need participants to help you interpret it.
+
+- "We've seen a lot of people [behavior observed in data]. Does that match your experience?"
+- "Some of the people we've talked to have told us [finding]. How does that land for you?"
+- "We see that users often drop off at [step]. Does that step feel like a natural stopping point to you?"
+- "Looking at this [flow / page / report], what feels most and least useful to you?"
+
+**Important:** When referencing prior findings, present the observation without the interpretation. Let participants react to what happened, not to your conclusion about why.
+
+---
+
+## Probing Follow-Ups (Universal)
+
+Keep these ready for any interview. They are domain-agnostic and work in any research phase.
+
+| Situation | Probe |
+|-----------|-------|
+| Participant gives a vague answer | "Can you give me an example of that?" |
+| Participant makes a claim | "When did that last happen?" |
+| Participant says something surprising | "Say more about that." |
+| Participant hesitates | [Wait. Count to five in your head. Then ask:] "What's making you pause?" |
+| Participant says "usually" | "Walk me through the last time that happened." |
+| Participant gives a short answer | "What else?" |
+| Participant mentions someone else | "What does [person] think about that?" |
+| Participant uses a word you don't recognize | "When you say [word], what do you mean by that?" |
+| Participant says "it depends" | "What does it depend on?" |
+| Participant gives a very positive answer | "What's the thing you would most want to change, even if everything else stayed the same?" |
+
+---
+
+## Questions to Avoid
+
+These questions are common but produce low-quality data. Replace them with the alternatives below.
+
+| Avoid | Why | Use Instead |
+|-------|-----|-------------|
+| "Would you use this?" | Hypothetical behavior is unreliable | "When did you last need to do something like this?" |
+| "Do you like it?" | Yes/no with no signal | "What's working for you? What isn't?" |
+| "Don't you think that's confusing?" | Leading | "What was your reaction when you saw that?" |
+| "What features do you want?" | Invites solution ideas, not problem insight | "What's the hardest part of doing this today?" |
+| "Is this easy to use?" | Leading toward a positive answer | "Walk me through how you'd use this." |
+| "What would make this better?" | Too abstract, disconnected from behavior | "Tell me about a time when something similar let you down." |

package/opencode/skill/user-research/examples/personas.md

@@ -0,0 +1,267 @@
+# Persona Examples
+
+## Context
+
+This document shows what complete personas look like in practice. It includes two contrasting examples -- a proto-persona built from assumptions before research, and a research-backed persona built from interview synthesis -- followed by a blank template for new personas.
+
+The key distinction between these types is not format but evidence. A proto-persona is a documented hypothesis. A research-backed persona is a finding. Both are useful. Neither should be mistaken for the other.
+
+---
+
+## Proto-Persona (Assumption-Based)
+
+Proto-personas are created before or instead of research, usually to align a team on a shared working hypothesis or to plan a study. They are honest about their origins -- they represent what the team believes, not what users have confirmed.
+
+Label all proto-personas clearly. Treat them as assumptions to be tested.
+
+---
+
+```
+NAME: Marcus Chen
+TITLE: Founder, early-stage B2B SaaS startup
+ARCHETYPE: Resourceful Builder
+
+SOURCE: PROTO-PERSONA -- based on team assumptions,
+not validated with research
+
+QUOTE:
+"I need to move fast. I'll figure out the proper way
+to do it once we have traction."
+
+DEMOGRAPHICS:
+Age: 28-38     Experience: 2-6 years as founder
+Context: Remote, works across product / sales / ops
+Team size: 1-8 people
+
+GOALS:
+- Primary: Ship product quickly to validate the market
+- Secondary: Keep costs low while reaching first $10K MRR
+
+PAIN POINTS (ASSUMED):
+- Too many tools pulling attention in different directions
+- No dedicated ops or admin support -- does everything
+- Hard to prioritize when everything feels urgent
+
+BEHAVIORS (ASSUMED):
+- Heavy Twitter / X and Slack user
+- Prefers products with quick time-to-value, no onboarding
+- Makes purchase decisions alone, often on impulse
+- Will switch tools if something cheaper appears
+
+TECH COMFORT: High. Will use APIs, configure webhooks,
+read docs to solve problems independently.
+
+OPEN ASSUMPTIONS (MUST TEST):
+- Do founders actually buy this themselves, or do they
+  delegate it once they see traction?
+- Is speed really the primary value, or is it trust /
+  reliability?
+- Does this segment actually experience the pain we think?
+
+SCENARIO:
+Marcus discovers the product through a tweet, signs up for
+a free trial without reading the landing page in full, and
+tries to connect his existing stack in the first 10 minutes.
+If he hits a wall, he leaves. If it works, he upgrades.
+```
+
+**When to use a proto-persona:**
+- Early in a project before research is possible
+- To align stakeholders on who you are and are not designing for
+- To scope a research study by making assumptions explicit
+
+**Important constraint from SKILL.md:** Proto-personas must never be presented as research findings. They are a starting position, not a conclusion. Label them explicitly and use them to drive research, not replace it.
+
+---
+
+## Research-Backed Persona
+
+Research-backed personas are synthesized from multiple interview participants. Each attribute is grounded in observed behavior or direct quotes from at least two to three participants. The evidence column is the most important part -- it is what separates a persona from a guess.
+
+---
+
+```
+NAME: Priya Nair
+TITLE: Operations Lead, mid-size B2B software company
+ARCHETYPE: The Reluctant Coordinator
+
+SOURCE: RESEARCH-BACKED -- synthesized from 9 interviews,
+validated across 3 participant segments
+
+QUOTE:
+"My job is to make sure nothing falls through the cracks.
+The problem is I'm always finding out too late that
+something already did."
+-- P4, Operations Lead, 6 years experience
+
+DEMOGRAPHICS:
+Age: 30-45     Experience: 4-10 years in ops roles
+Context: Office or hybrid; manages cross-functional
+workflows across teams of 20-80 people
+
+GOALS:
+- Primary: Maintain visibility across all in-flight work
+  without becoming the bottleneck for every update
+- Secondary: Reduce meeting load by making status visible
+  asynchronously
+
+PAIN POINTS (EVIDENCE-BACKED):
+
+1. Status is scattered across too many places
+   Evidence: 7/9 participants described checking 3+ tools
+   (email, Slack, spreadsheets, project tools) just to
+   answer "where does this stand?"
+   Quote: "I have four tabs open just to give one update."
+   -- P7
+
+2. Escalations arrive too late
+   Evidence: 6/9 participants described situations where a
+   problem surfaced at standup or in a meeting that should
+   have been flagged a day or more earlier
+   Quote: "By the time I hear about it, the deadline is
+   already at risk." -- P2
+
+3. Reminder and follow-up work is manual and time-consuming
+   Evidence: 5/9 participants manually tracked who had
+   responded to requests via spreadsheet or flagged emails
+   Quote: "I paste the same message into Slack three times
+   a week just to get a response." -- P4
+
+BEHAVIORS (OBSERVED):
+- Builds personal tracking systems (spreadsheets, Notion
+  pages) to compensate for tool fragmentation
+- Sends Slack messages rather than creating formal tickets
+  because it's faster, even when a ticket would help more
+- Prefers to check status herself rather than interrupt
+  teammates -- respects others' focus time
+- Exports data from tools manually to create summary reports
+  for leadership on a weekly basis
+
+TECH COMFORT: Medium. Uses existing tools confidently but
+does not configure integrations or write automations. Relies
+on IT or engineering for anything technical.
+
+SCENARIO:
+It is 3:00 PM on a Thursday. Priya has a leadership sync in
+90 minutes and needs to confirm that three open deliverables
+are on track. She opens Slack to message three different
+people, checks the project tool to see if statuses were
+updated (they were not), then falls back to her spreadsheet.
+She composes a "quick update" message that takes 20 minutes
+to send because she doesn't want to seem like she's nagging.
+She goes into the sync knowing she has incomplete info.
+
+DESIGN IMPLICATIONS:
+- Visibility without friction is the core value proposition
+- Automation must reduce her work, not create new admin
+- Notifications must be smart -- she is already overwhelmed
+- Language should not feel corporate -- she uses informal
+  channels by choice
+```
+
+**What makes this persona research-backed:**
+- Every pain point cites the number of participants who expressed it
+- At least one direct quote supports each attribute
+- Behaviors describe observed actions, not inferred preferences
+- Design implications follow from the evidence, not from assumptions
+
+---
+
+## Negative Persona Example
+
+Negative personas define who the product is not designed for. They prevent design decisions from being pulled toward the wrong user by stakeholders who advocate for edge cases.
+
+```
+NAME: "The Power Admin"
+ARCHETYPE: Deep configurator, technically proficient
+
+WHY NOT OUR USER:
+This person needs granular permission controls, custom
+workflow logic, and API access. Designing for their needs
+would add complexity that makes our product harder to use
+for Priya -- our primary persona.
+
+They are better served by [enterprise competitor].
+
+REFERENCE:
+When a stakeholder requests a feature that only a power
+admin would use, refer back to this persona to ground the
+conversation in tradeoffs.
+```
+
+---
+
+## Blank Persona Template
+
+Copy this template when creating personas from a new research study. Fill in only what your research supports. Leave fields blank rather than filling them with assumptions -- missing evidence is better than fabricated evidence.
+
+```
+NAME: [Fictional name]
+TITLE: [Role / context]
+ARCHETYPE: [2-3 word descriptor]
+
+SOURCE: [ ] PROTO-PERSONA (assumptions)
+        [ ] RESEARCH-BACKED (synthesized from N interviews)
+
+QUOTE:
+"[Direct quote from a participant -- attribute to P#]"
+
+DEMOGRAPHICS:
+Age: [Range]     Experience: [Level / years]
+Context: [Work environment, team size, role scope]
+
+GOALS:
+- Primary: [Main objective -- what success looks like]
+- Secondary: [Supporting objective]
+
+PAIN POINTS:
+
+1. [Pain point headline]
+   Evidence: [N/N participants; direct quote -- P#]
+
+2. [Pain point headline]
+   Evidence: [N/N participants; direct quote -- P#]
+
+3. [Pain point headline]
+   Evidence: [N/N participants; direct quote -- P#]
+
+BEHAVIORS:
+- [How they approach the problem domain]
+- [Tools, workarounds, or systems they have built]
+- [Decision-making patterns relevant to your product]
+- [Social / collaborative behavior -- who do they involve?]
+
+TECH COMFORT: [Low / Medium / High -- describe what they
+can and cannot do independently]
+
+OPEN QUESTIONS: (for proto-personas only)
+- [Assumption that still needs validation]
+- [Assumption that still needs validation]
+
+SCENARIO:
+[A concrete, present-tense narrative of this persona
+experiencing the core problem your product addresses.
+3-6 sentences. Specific details, not generalities.]
+
+DESIGN IMPLICATIONS:
+- [What this persona requires from the product]
+- [What would break trust or cause abandonment]
+- [Constraints on complexity, workflow, or tone]
+```
+
+---
+
+## Persona Quality Checklist
+
+Before sharing a persona with stakeholders, verify:
+
+- [ ] The persona type (proto vs. research-backed) is clearly labeled
+- [ ] Every pain point cites the number of participants who confirmed it
+- [ ] At least one direct quote supports each claim
+- [ ] The quote is attributed to a participant ID, not paraphrased
+- [ ] Behaviors describe observed actions, not inferred preferences
+- [ ] The scenario is specific enough to use in a design critique
+- [ ] Design implications follow directly from evidence
+- [ ] The persona has been reviewed against at least 3 participant transcripts
+
+**Fail condition:** If a team member reads the persona and cannot tell which attributes are observed vs. assumed, the persona needs revision.