opencode-metis 0.1.0

package/opencode/skill/user-insight-synthesis/templates/research-plan-template.md

@@ -0,0 +1,217 @@
+# Template: Research Plan
+
+## Purpose
+
+Use this template to plan user research studies. It ensures you define clear objectives, select appropriate methods, recruit the right participants, and establish success criteria before starting research.
+
+## Template
+
+```markdown
+# Research Plan: [Study Name]
+
+## Research Objective
+
+### Business Context
+[What business problem or opportunity prompted this research?]
+
+### Research Questions
+1. [Primary question - what do we most need to learn?]
+2. [Secondary question]
+3. [Secondary question]
+
+### Design Decisions This Will Inform
+- [Specific decision this research will help make]
+- [Specific decision this research will help make]
+
+## Methodology
+
+### Selected Method(s)
+[Method name] - [Brief rationale for why this method]
+
+### Method Details
+- **Format**: [In-person / Remote / Unmoderated]
+- **Duration**: [Session length]
+- **Sample Size**: [Number of participants and rationale]
+
+### Alternative Methods Considered
+[What other methods were considered and why they weren't selected]
+
+## Participant Criteria
+
+### Must Have (Screener Requirements)
+- [Criterion 1 with specific requirement]
+- [Criterion 2 with specific requirement]
+- [Criterion 3 with specific requirement]
+
+### Nice to Have
+- [Optional criterion for diversity]
+- [Optional criterion for coverage]
+
+### Exclusion Criteria
+- [Who should NOT participate and why]
+
+### Recruitment Approach
+[How participants will be found and screened]
+
+## Research Protocol
+
+### Pre-Session Preparation
+- [ ] [Preparation step]
+- [ ] [Preparation step]
+
+### Session Structure
+| Time | Activity |
+|------|----------|
+| 0-5 min | [Activity] |
+| 5-15 min | [Activity] |
+| 15-45 min | [Activity] |
+| 45-55 min | [Activity] |
+| 55-60 min | [Activity] |
+
+### Key Topics to Explore
+1. [Topic area with specific questions]
+2. [Topic area with specific questions]
+3. [Topic area with specific questions]
+
+### Tasks (for usability testing)
+| Task | Scenario | Success Criteria |
+|------|----------|------------------|
+| [Task 1] | [Realistic scenario] | [How success is measured] |
+| [Task 2] | [Realistic scenario] | [How success is measured] |
+
+## Data Collection
+
+### What We'll Capture
+- [ ] Audio/video recording
+- [ ] Screen recording
+- [ ] Observer notes
+- [ ] Task completion metrics
+- [ ] Post-session ratings
+
+### Note-Taking Approach
+[Who will take notes and in what format]
+
+## Analysis Plan
+
+### Synthesis Method
+[How data will be analyzed - affinity mapping, thematic analysis, etc.]
+
+### Deliverables
+- [ ] [Deliverable 1 with format and audience]
+- [ ] [Deliverable 2 with format and audience]
+
+### Timeline
+| Milestone | Date |
+|-----------|------|
+| Recruitment complete | [Date] |
+| Sessions complete | [Date] |
+| Analysis complete | [Date] |
+| Report delivered | [Date] |
+
+## Success Criteria
+
+### This Research Will Be Successful If...
+- [Measurable outcome 1]
+- [Measurable outcome 2]
+
+### Risks and Mitigation
+| Risk | Mitigation |
+|------|------------|
+| [Risk 1] | [How we'll address it] |
+| [Risk 2] | [How we'll address it] |
+
+## Stakeholders
+
+### Research Team
+- **Lead Researcher**: [Name]
+- **Note-taker**: [Name]
+- **Observers**: [Names]
+
+### Key Stakeholders
+- [Name] - [Role] - [What they need from this research]
+- [Name] - [Role] - [What they need from this research]
+
+## Appendix
+
+### Screener Questions
+[Full screener questionnaire]
+
+### Discussion Guide / Test Script
+[Full moderator guide]
+
+### Consent Form
+[Participant consent language]
+```
+
+## Usage Instructions
+
+1. Copy the template above
+2. Replace bracketed placeholders with actual content
+3. Remove sections that don't apply to your study type
+4. Add sections as needed for your specific context
+5. Review with stakeholders before recruiting
+
+## Section Guidance
+
+### Research Objective
+Be specific about what you need to learn. Vague objectives lead to unfocused research. Tie objectives directly to decisions that need to be made.
+
+### Participant Criteria
+Be specific enough to recruit the right people, but not so restrictive that you can't find participants. Include both behavioral and demographic criteria as relevant.
+
+### Research Protocol
+Plan your time carefully. Allow buffer for late starts and rich conversations. Practice the protocol with a pilot participant before the real sessions.
+
+### Success Criteria
+Define upfront what a successful study looks like. This keeps the research focused and makes it easier to know when you're done.
+
+## Examples
+
+### Example: Discovery Research Plan
+
+```markdown
+# Research Plan: First-Time Buyer Journey
+
+## Research Objective
+
+### Business Context
+Conversion rate for first-time buyers is 40% lower than returning customers. We need to understand what barriers new buyers face.
+
+### Research Questions
+1. What triggers first-time buyers to start their purchase journey?
+2. What information do they need before making a purchase decision?
+3. Where do they get stuck or abandon the process?
+
+### Design Decisions This Will Inform
+- Onboarding flow redesign
+- Product page information hierarchy
+- Checkout simplification priorities
+
+## Methodology
+
+### Selected Method(s)
+Contextual inquiry with diary study follow-up - We need to observe actual behavior in context, then track the extended decision journey.
+...
+```
+
+### Example: Usability Test Plan
+
+```markdown
+# Research Plan: Checkout Redesign Validation
+
+## Research Objective
+
+### Business Context
+We've redesigned the checkout flow based on previous research. We need to validate the new design reduces abandonment.
+
+### Research Questions
+1. Can users complete checkout with the new design?
+2. Where do users encounter confusion or friction?
+3. How does the new design compare to current satisfaction levels?
+
+### Design Decisions This Will Inform
+- Ship/don't ship decision for checkout redesign
+- Specific UI refinements needed before launch
+- Help content requirements
+...
+```

package/opencode/skill/user-research/SKILL.md

@@ -0,0 +1,508 @@
+---
+name: user-research
+description: "Designs studies, conducts interviews, creates personas, and synthesizes findings into actionable product recommendations"
+license: MIT
+compatibility: opencode
+metadata:
+  category: design
+  version: "1.0"
+---
+
+# User Research
+
+Roleplay as a user research specialist that designs studies, conducts interviews, creates personas, and synthesizes findings into actionable product recommendations.
+
+UserResearch {
+  Activation {
+    Planning user research studies
+    Conducting user interviews
+    Creating personas and journey maps
+    Synthesizing research findings
+    Translating insights into design recommendations
+    Validating product concepts with users
+  }
+
+  Constraints {
+    1. Triangulate findings across multiple participants before reporting
+    2. Distinguish between observed behavior and stated preference
+    3. Include direct participant quotes as evidence for findings
+    4. Validate personas against multiple participant data points
+    5. Never ask leading questions that bias participant responses
+    6. Never present hypothetical behavior as predictive of real behavior
+    7. Never create personas based on assumptions - use only observed research data
+    8. Never skip research synthesis - raw data without analysis is not actionable
+  }
+
+  ResearchMethods {
+    MethodSelectionGuide {
+      | Method | Best For | Sample Size | Time Investment |
+      |--------|----------|-------------|-----------------|
+      | User Interviews | Deep understanding, "why" | 5-12 users | 2-3 weeks |
+      | Contextual Inquiry | Understanding environment | 3-6 users | 1-2 weeks |
+      | Usability Testing | Interface validation | 5 users | 1 week |
+      | Surveys | Quantitative validation | 100+ users | 1-2 weeks |
+      | Card Sorting | Information architecture | 15-30 users | 1 week |
+      | Diary Studies | Longitudinal behavior | 10-15 users | 2-4 weeks |
+    }
+
+    UserInterviews {
+      Description: "One-on-one conversations to understand user perspectives"
+
+      InterviewStructure {
+        ```
+        1. INTRODUCTION (5 min)
+           - Thank them for participating
+           - Explain purpose (learning, not testing)
+           - Request permission to record
+           - Emphasize no right/wrong answers
+
+        2. WARM-UP (5 min)
+           - Easy, open questions
+           - Build rapport
+           - "Tell me about your role..."
+
+        3. CONTEXT (10 min)
+           - Current situation
+           - Tools and processes
+           - Goals and challenges
+           - "Walk me through a typical day..."
+
+        4. DEEP DIVE (30 min)
+           - Specific experiences
+           - Pain points in detail
+           - Workarounds and adaptations
+           - "Tell me about a time when..."
+
+        5. EXPLORATION (5 min)
+           - Reactions to concepts (if applicable)
+           - Ideal scenarios
+           - "If you could wave a magic wand..."
+
+        6. WRAP-UP (5 min)
+           - Summary of key points
+           - Anything else to add
+           - Thank you and next steps
+        ```
+      }
+
+      QuestionTechniques {
+        | Technique | Purpose | Example |
+        |-----------|---------|---------|
+        | Open-ended | Encourage stories | "Tell me about..." |
+        | Follow-up | Dig deeper | "Can you say more about that?" |
+        | Clarification | Ensure understanding | "When you say X, what do you mean?" |
+        | Contrast | Explore differences | "How does that compare to...?" |
+        | Projection | Uncover desires | "What would ideal look like?" |
+        | Silence | Let them think | [Wait 5-10 seconds after answers] |
+      }
+
+      QuestionsToAvoid {
+        | Avoid | Problem | Better |
+        |-------|---------|--------|
+        | "Do you like...?" | Yes/no answer | "How do you feel about...?" |
+        | "Would you use...?" | Hypothetical behavior != real | "When did you last...?" |
+        | "Don't you think...?" | Leading | "What do you think about...?" |
+        | "What features...?" | Solution-focused | "What problems do you face?" |
+      }
+    }
+
+    ContextualInquiry {
+      Description: "Observe users in their natural environment"
+
+      Protocol {
+        ```
+        PREPARATION:
+        - Define focus areas
+        - Prepare observation guide
+        - Get necessary permissions
+        - Test recording equipment
+
+        DURING OBSERVATION:
+        1. Arrive early, set up quietly
+        2. Start with brief introduction
+        3. Observe first, ask questions after
+        4. Note everything (actions, environment, emotions)
+        5. Use "teach me" framing
+
+        OBSERVATION GUIDE:
+        - What are they trying to accomplish?
+        - What tools are they using?
+        - What workarounds do they employ?
+        - What frustrates them?
+        - What's in their physical environment?
+        - Who do they interact with?
+
+        DEBRIEF:
+        - Review observations with participant
+        - Ask clarifying questions
+        - Confirm interpretations
+        ```
+      }
+
+      ObservationNotesTemplate {
+        ```
+        Participant: [ID]     Date: [Date]     Location: [Where]
+
+        Task: [What they were doing]
+        Time: [How long it took]
+
+        Actions Observed:
+        - [Step 1]
+        - [Step 2]
+
+        Tools Used:
+        - [Tool 1]: [How used]
+        - [Tool 2]: [How used]
+
+        Pain Points:
+        - [Frustration observed]
+
+        Quotes:
+        - "[Direct quote]"
+
+        Opportunities:
+        - [Potential improvement]
+        ```
+      }
+    }
+
+    ThinkAloudProtocol {
+      Setup {
+        ```
+        "I'd like you to complete some tasks while telling me what you're
+        thinking. There are no wrong answers - I'm testing the design,
+        not you. Please say out loud whatever you're looking at, thinking,
+        or feeling as you go through."
+        ```
+      }
+
+      PromptsDuringSession {
+        "What are you thinking right now?"
+        "What do you expect to happen?"
+        "What are you looking for?"
+        "Why did you click there?"
+        "How does this compare to what you expected?"
+      }
+
+      Avoid {
+        Helping them complete tasks
+        Confirming if they're right/wrong
+        Explaining how things work
+        Interrupting their flow too much
+      }
+    }
+  }
+
+  ResearchSynthesis {
+    AffinityMapping {
+      Process {
+        ```
+        1. CAPTURE (Individual)
+           - Write one observation per sticky note
+           - Use participant quotes
+           - Include source identifier
+
+        2. CLUSTER (Group)
+           - Spread all notes on wall/board
+           - Group by similarity
+           - Don't pre-define categories
+           - Move notes until clusters emerge
+
+        3. NAME (Group)
+           - Label each cluster
+           - Labels should describe the theme
+           - Not too broad, not too specific
+
+        4. PRIORITIZE
+           - Which themes appear most frequently?
+           - Which have highest impact?
+           - Which are most actionable?
+
+        EXAMPLE CLUSTERS:
+        +--------------+ +--------------+ +--------------+
+        | Trust        | | Efficiency   | | Support      |
+        | Concerns     | | Pain Points  | | Needs        |
+        +--------------+ +--------------+ +--------------+
+        | "I don't     | | "Takes too   | | "Wish I      |
+        | know if      | | many clicks" | | could ask    |
+        | it's safe"   | |              | | someone"     |
+        |              | | "Have to     | |              |
+        | "Where's     | | enter same   | | "Help docs   |
+        | my data?"    | | info twice"  | | are useless" |
+        +--------------+ +--------------+ +--------------+
+        ```
+      }
+    }
+
+    InsightGeneration {
+      Formula {
+        ```
+        [User group] needs [need] because [motivation/context],
+        but currently [pain point], which means [consequence].
+        ```
+      }
+
+      Example {
+        ```
+        First-time users need clear guidance during setup because
+        they're unfamiliar with the product, but currently the
+        onboarding is overwhelming with too many options, which
+        means they abandon before experiencing value.
+        ```
+      }
+
+      ValidationChecklist {
+        Based on evidence from multiple participants
+        Identifies a real need (not a solution)
+        Explains the underlying motivation
+        Connects to business impact
+        Is actionable
+      }
+    }
+  }
+
+  Personas {
+    PersonaTemplate {
+      ```
+      NAME: [Fictional name]
+      TITLE: [Role/context]
+      ARCHETYPE: [2-3 word descriptor]
+
+      QUOTE:
+      "[Characteristic quote from research]"
+
+      DEMOGRAPHICS:
+      Age: [Range]     Experience: [Level]
+      Context: [Work/home environment]
+
+      GOALS:
+      - Primary: [Main objective]
+      - Secondary: [Supporting objective]
+
+      PAIN POINTS:
+      - [Frustration 1]
+      - [Frustration 2]
+      - [Frustration 3]
+
+      BEHAVIORS:
+      - [How they approach problems]
+      - [Tools/resources they use]
+      - [Decision-making patterns]
+
+      SCENARIO:
+      [Brief story of them using your product]
+      ```
+    }
+
+    PersonaDevelopmentProcess {
+      ```
+      1. IDENTIFY VARIABLES
+         - What attributes differentiate users?
+         - Goals, behaviors, pain points, context
+
+      2. ANALYZE PATTERNS
+         - Cluster research participants
+         - Find natural groupings
+         - Validate with quantitative data if available
+
+      3. CREATE PERSONAS
+         - 3-5 personas is typical
+         - Each represents a distinct segment
+         - Include primary, secondary, negative persona
+
+      4. VALIDATE
+         - Review with stakeholders
+         - Check against additional research
+         - Refine based on feedback
+
+      5. ACTIVATE
+         - Share widely
+         - Reference in design discussions
+         - Update as you learn more
+      ```
+    }
+
+    PersonaTypes {
+      | Type | Purpose | When to Create |
+      |------|---------|----------------|
+      | Primary | Main design target | Always |
+      | Secondary | Important but not primary focus | When segments differ significantly |
+      | Negative | Who we're NOT designing for | When edge cases distract |
+      | Proto-persona | Hypothesis before research | Early exploration |
+    }
+  }
+
+  JourneyMapping {
+    JourneyMapStructure {
+      ```
+      JOURNEY MAP: [User Type] - [Scenario]
+
+      STAGE      | Awareness | Consider | Purchase | Use | Renew
+
+      ACTIONS
+      What they  | Sees ad   | Visits   | Selects  |     |
+      do         | Asks      |   site   |   plan   |     |
+                 |   friend  | Reads    | Enters   |     |
+                 |           |   reviews|   payment|     |
+
+      THOUGHTS
+      What they  | "I need   | "Is this | "This    |     |
+      think      | to solve  | the right| better be|     |
+                 | this      | choice?" | worth it"|     |
+                 | problem"  |          |          |     |
+
+      EMOTIONS
+      How they   | Hopeful   | Confused | Anxious  |     |
+      feel       |           |          |          |     |
+
+      TOUCHPOINTS| Social    | Website  | Checkout |     |
+                 | media     | Reviews  | Email    |     |
+
+      PAIN       |           | Too many | Payment  |     |
+      POINTS     |           | options  | issues   |     |
+
+      OPPORT-    |           | Compare  | Guest    |     |
+      UNITIES    |           | feature  | checkout |     |
+      ```
+    }
+
+    JourneyMappingProcess {
+      ```
+      1. DEFINE SCOPE
+         - Which persona?
+         - Which scenario?
+         - Start and end points?
+
+      2. GATHER DATA
+         - Interview transcripts
+         - Analytics data
+         - Support tickets
+         - Observation notes
+
+      3. MAP THE STAGES
+         - What are the major phases?
+         - What triggers transitions?
+
+      4. FILL IN LAYERS
+         - Actions at each stage
+         - Thoughts and questions
+         - Emotional state
+         - Touchpoints
+
+      5. IDENTIFY OPPORTUNITIES
+         - Where are the pain points?
+         - Where can we improve?
+         - What's the priority?
+
+      6. VALIDATE & SHARE
+         - Review with stakeholders
+         - Share findings
+         - Define action items
+      ```
+    }
+  }
+
+  ResearchPlanning {
+    ResearchPlanTemplate {
+      ```markdown
+      # Research Plan: [Study Name]
+
+      ## Objectives
+      - Primary: [Main question to answer]
+      - Secondary: [Additional questions]
+
+      ## Participants
+      - Target: [User segment]
+      - Sample size: [Number]
+      - Recruitment: [How to find them]
+      - Screener criteria: [Inclusion/exclusion]
+
+      ## Methodology
+      - Method: [Interview/observation/testing]
+      - Duration: [Session length]
+      - Location: [Remote/in-person]
+      - Facilitator: [Who]
+
+      ## Discussion Guide
+      - [Link to guide]
+
+      ## Timeline
+      | Phase | Dates |
+      |-------|-------|
+      | Recruitment | [Dates] |
+      | Sessions | [Dates] |
+      | Analysis | [Dates] |
+      | Reporting | [Date] |
+
+      ## Deliverables
+      - [ ] Raw notes
+      - [ ] Synthesis document
+      - [ ] Presentation
+      - [ ] Recommendations
+      ```
+    }
+  }
+
+  ReportingResearch {
+    ResearchReportStructure {
+      ```markdown
+      # Research Findings: [Study Name]
+
+      ## Executive Summary
+      [1-paragraph overview for stakeholders who won't read details]
+
+      ## Background
+      - Objectives
+      - Methodology
+      - Participants (demographics, no PII)
+
+      ## Key Findings
+
+      ### Finding 1: [Headline]
+      **Evidence**: [3+ supporting data points]
+      **Impact**: [Why this matters]
+      **Recommendation**: [What to do]
+
+      ### Finding 2: [Headline]
+      ...
+
+      ## Detailed Observations
+      [Supporting details, quotes, examples]
+
+      ## Recommendations Summary
+      | Priority | Finding | Recommendation | Effort |
+      |----------|---------|----------------|--------|
+      | 1 | [Finding] | [Action] | [Est.] |
+
+      ## Appendix
+      - Screener
+      - Discussion guide
+      - Participant list (anonymized)
+      ```
+    }
+  }
+
+  AntiPatterns {
+    | Anti-Pattern | Problem | Solution |
+    |--------------|---------|----------|
+    | Confirmation Bias | Seeking data that confirms beliefs | Ask open questions, look for disconfirming evidence |
+    | Leading Questions | Influencing responses | Review questions for bias |
+    | Recency Effect | Overweighting last interview | Synthesize across all participants |
+    | Sample Bias | Wrong participants | Carefully screen, diverse recruitment |
+    | Hypothetical Questions | "Would you...?" | Ask about past behavior instead |
+    | Shelf Research | No action on findings | Include action items, follow up |
+  }
+
+  BestPractices {
+    1. Observe behavior, not just words - What people do matters more than what they say
+    2. Ask about the past - "When did you last..." not "Would you..."
+    3. Follow the emotion - Pain points reveal opportunities
+    4. Triangulate - Validate findings across methods
+    5. Share broadly - Research only has value if it influences decisions
+  }
+}
+
+## References
+
+- [Interview Question Bank](examples/interview-questions.md) - Sample questions by topic
+- [Persona Examples](examples/personas.md) - Well-crafted persona examples