oh-my-opencode 4.12.1 → 4.14.0

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/heuristic-evaluation/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: heuristic-evaluation
+description: "Use after a build to evaluate usability against Nielsen's 10 heuristics and run cognitive walkthroughs of every key task. Dispatches the heuristic-evaluator agent in parallel with design-critic and accessibility-reviewer, then feeds findings into the reconciliation protocol. This is the usability lens — \"will people actually be able to use this?\" — distinct from craft critique and accessibility audit"
+---
+
+# Heuristic Evaluation
+
+Heuristic evaluation is the usability lens on a build. Where `designpowers-critique` asks "does this match the plan?" and the accessibility review asks "can everyone access this?", heuristic evaluation asks "will people actually be able to use this without getting lost, confused, or stuck?" This skill dispatches the **heuristic-evaluator** agent and integrates its findings with the other reviewers.
+
+## When to Use
+
+- **After `design-builder` completes a build** — run alongside `designpowers-critique` and the accessibility review, not after them
+- Before a fix round, so usability findings are reconciled with craft and accessibility findings together
+- When a flow feels confusing but you can't articulate why — the heuristics name the problem
+- When evaluating an existing design (see `using-designpowers` → Review Mode), not just freshly built work
+
+This skill is **not optional after a build.** Skipping it is a Red Flag (see `using-designpowers`). Usability problems that craft critique and accessibility audits both miss are exactly what this catches.
+
+## Process
+
+### Step 1: Confirm Inputs Exist
+
+Before dispatching, assemble:
+- The **build** to evaluate (running app, prototype, or screenshots — test what was built, not the spec)
+- The **design brief** (from `design-discovery`) — for the key tasks to walk through
+- The **personas** (from `inclusive-personas`) — each persona's primary task gets a cognitive walkthrough
+- `design-state.md` — the shared state the agent will read and update
+
+If there is no brief or no list of key tasks, the cognitive walkthrough has nothing to walk through. Go back and capture the key tasks first.
+
+### Step 2: Dispatch the heuristic-evaluator Agent
+
+Dispatch the `heuristic-evaluator` agent (see `agents/heuristic-evaluator.md`). It will:
+
+1. Evaluate the interface against **Nielsen's 10 heuristics**, citing specific violations with evidence (H1–H10)
+2. Run a **cognitive walkthrough** of every key task — four questions per step
+3. Analyse **error paths**, not just happy paths — recovery, undo, back navigation, dead ends
+4. Assess **learnability** (first-time user) and **efficiency** (repeat user)
+5. Acknowledge what works well, not only what fails
+
+The agent narrates at three moments (arrival, working, departure) per the Agent Transparency protocol in `using-designpowers`.
+
+### Step 3: Run in Parallel and Reconcile
+
+Per the **Reconciliation Protocol** in `using-designpowers`, the heuristic-evaluator runs **simultaneously** with `design-critic` and the accessibility-reviewer:
+
+```
+design-builder finishes
+        |
+   ┌────┼────────┐
+   v    v        v
+critic  reviewer  heuristic    (run simultaneously)
+   |    |        |
+   └────┼────────┘
+        v
+  reconciliation
+```
+
+When findings overlap or conflict, classify them (Aligned / Complementary / Conflicting) and resolve using the protocol's priority rules. Remember: **usability wins over style** — a beautiful interface that confuses people has failed.
+
+### Step 4: Honour the Auto-Mode Safeguard
+
+Even in auto mode, the pipeline **must pause** if the heuristic-evaluator finds a critical **H3 violation** (no undo on a destructive action) or **H1 violation** (user is completely lost). These indicate structural problems, not polish issues, and the user should decide how to resolve them.
+
+> ⚠️ **Auto paused:** heuristic-evaluator found a critical usability issue (H3 — no undo on delete) that needs your decision. [details]
+
+### Step 5: Feed the Fix Round
+
+After reconciliation:
+1. The agent's findings join the single prioritised fix list (critical first)
+2. Note which findings the heuristic-evaluator sourced and whether any were reconciled with other reviewers
+3. **Record deferred Minor findings** in the Design Debt Register via `design-debt-tracker` — promises don't disappear because severity is low
+4. Re-run the heuristic-evaluator only on critical fixes after the build round, not the full evaluation
+
+## What You Get
+
+A structured heuristic evaluation report (see the agent definition for the full format): a heuristic findings table (H1–H10 with verdicts), cognitive walkthrough results per task, findings grouped by severity, what works well, and a recommendation (Proceed / Revise / Rethink).
+
+## Integration
+
+- **Runs after:** `design-builder` (build complete) — or against an existing design in Review Mode
+- **Runs alongside:** `designpowers-critique`, accessibility review (parallel, then reconciled)
+- **Feeds:** the reconciliation protocol → `design-builder` fix round → `synthetic-user-testing`
+- **Calls:** `design-debt-tracker` for deferred Minor findings
+- **Records to:** `design-state.md` (Decisions Log, Handoff Chain, Open Questions)

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/inclusive-personas/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: inclusive-personas
+description: "Use when defining who a design serves — creating personas, user stories, or scenarios — ensures the full ability spectrum and situational contexts are represented from the start, not retrofitted"
+---
+
+# Inclusive Personas
+
+Personas shape every design decision that follows. If your personas only represent able-bodied, neurotypical, tech-savvy adults with fast internet, your design will only work for those people. This skill ensures the full range of human experience is represented from the beginning.
+
+## The Principle
+
+"Nothing About Us Without Us." Design for the margins and the centre benefits. Design for the centre and the margins get excluded.
+
+## Process
+
+### Step 1: Map the Ability Spectrum
+
+For the design context, identify the relevant spectrum across:
+
+**Permanent conditions:**
+- Vision: blind, low vision, colour blind
+- Hearing: deaf, hard of hearing
+- Motor: limited fine motor, limited reach, tremor, paralysis
+- Cognitive: learning differences, memory challenges, attention differences
+- Speech: non-verbal, speech differences
+
+**Temporary conditions:**
+- Broken arm, ear infection, concussion, medication effects, post-surgery
+
+**Situational conditions:**
+- Bright sunlight, noisy environment, one hand occupied, driving, multitasking, emotional distress, unfamiliar language, slow connection
+
+### Step 2: Identify Relevant Personas
+
+Not every project needs every persona. Select 4-6 personas that represent:
+- **2-3 primary users** — the most common use cases
+- **1-2 edge case users** — people at the margins whose needs reveal design weaknesses
+- **1 stress case user** — someone using the design under difficult circumstances
+
+### Step 3: Build Each Persona
+
+For each persona, document:
+
+```markdown
+## [Name]
+
+**Context:** [Who they are, what they do, their relationship to this product]
+
+**Abilities and conditions:** [Permanent, temporary, or situational factors that affect how they interact with interfaces]
+
+**Technology:** [Devices, assistive technology, connection speed, technical confidence]
+
+**Goals:** [What they need to accomplish]
+
+**Frustrations:** [What typically goes wrong for them with similar products]
+
+**Environment:** [Where and when they use this — lighting, noise, distractions, time pressure]
+```
+
+### Step 4: Write Inclusive User Stories
+
+For each persona, write stories that capture:
+- The standard path: "As [persona], I want to [goal] so that [outcome]"
+- The assisted path: "As [persona] using [assistive technology], I want to [goal] so that [outcome]"
+- The stress path: "As [persona] under [stressful condition], I need to [goal] without [negative outcome]"
+
+### Step 5: Identify Scenario Intersections
+
+Map where personas overlap in unexpected ways:
+- A sighted user in bright sunlight has similar needs to a low-vision user
+- A stressed parent holding a baby has similar motor constraints to someone with limited hand mobility
+- A non-native speaker has similar needs to someone with a cognitive processing difference
+
+These intersections reveal universal design opportunities.
+
+### Step 6: Present and Validate
+
+Present personas to the user. Ask:
+- Who is missing from this set?
+- Do these feel like real people or cardboard cutouts?
+- Which persona makes you most uncomfortable? (That one probably needs the most attention)
+
+Save to: `docs/designpowers/personas/YYYY-MM-DD-<project>-personas.md`
+
+## Integration
+
+- **Called by:** `research-planning`, `design-discovery`
+- **Informs:** Every subsequent design skill — personas should be referenced when making any design decision
+- **Pairs with:** `cognitive-accessibility`, `adaptive-interfaces`
+
+## Anti-Patterns
+
+| Pattern | Problem |
+|---------|---------|
+| "Our users are everyone" | If everyone is your user, nobody is. Define specific people |
+| Personas without disabilities | You have excluded a quarter of the population |
+| Edge cases treated as afterthoughts | Edge cases reveal the quality of your design. They come first, not last |
+| Personas based on demographics alone | Age and job title do not determine how someone uses an interface. Focus on behaviour, ability, and context |

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/inspiration-scouting/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: inspiration-scouting
+description: "Use when the team needs aesthetic references, interaction examples, or visual inspiration beyond competitive research — finds design patterns, UI references, and creative approaches that match the brief and taste profile"
+---
+
+# Inspiration Scouting
+
+The design-scout does competitive research — who else solves this problem and how. Inspiration scouting is different. It finds aesthetic and interaction references that shape the *feel* of the design, even when they come from completely different domains. A banking app can be inspired by a meditation app's calm. A children's education tool can borrow pacing from a well-designed game.
+
+## When to Use
+
+- After design-discovery and design-strategy, before visual design begins
+- When the design-lead needs a visual direction and wants reference material
+- When the user says "show me some inspiration" or "what could this look like?"
+- When the taste profile exists but the project needs a fresh direction within it
+- When the team is stuck and needs outside input to break a creative block
+
+## Do Not Use When
+
+- The user has already provided specific visual references — use those directly
+- The design system is locked and visual direction is predetermined
+- The task is a fix or iteration, not a new direction
+
+## Process
+
+### Step 1: Define the Inspiration Brief
+
+Before searching, define what you're looking for:
+
+```markdown
+## Inspiration Brief
+
+**Project:** [Name and one-line description]
+**Feel we're going for:** [2-3 adjectives — e.g., "calm, confident, playful"]
+**Feel we're avoiding:** [2-3 adjectives — e.g., "clinical, childish, corporate"]
+**Taste constraints:** [From taste profile — known preferences and anti-patterns]
+**Domain:** [The project's domain — e.g., "pet care", "fintech", "education"]
+**Cross-domain openness:** [How far outside the domain to look — same domain / adjacent / anywhere]
+**Specific needs:** [e.g., "onboarding flow inspiration", "dashboard layout patterns", "empty state ideas"]
+```
+
+### Step 2: Search Across Layers
+
+Inspiration operates at multiple layers. Search each:
+
+#### Visual Layer
+- **Colour:** Palette approaches, colour psychology, brand colour usage
+- **Typography:** Type pairing, scale, weight distribution, editorial vs UI
+- **Layout:** Grid systems, density, whitespace philosophy, asymmetry
+- **Imagery:** Photography style, illustration approach, iconography
+- **Surface:** Texture, depth, glassmorphism, neumorphism, flat — what's appropriate
+
+#### Interaction Layer
+- **Navigation:** Patterns, transitions between views, wayfinding
+- **Feedback:** How the interface responds — micro-interactions, loading, success, error
+- **Onboarding:** First-run experiences, progressive disclosure, tutorials
+- **Data entry:** Form patterns, input methods, validation approaches
+- **Empty states:** What the app feels like before there's content
+
+#### Emotional Layer
+- **Personality:** How the interface expresses character through details
+- **Pacing:** Fast and efficient vs slow and contemplative
+- **Trust signals:** How the interface builds confidence
+- **Delight moments:** Where and how the interface surprises positively
+- **Restraint:** What the interface deliberately does *not* do
+
+### Step 3: Curate a Mood Board
+
+Compile findings into a structured mood board. Quality over quantity — 5 excellent references beat 20 mediocre ones.
+
+For each reference:
+
+```markdown
+### [Reference Name]
+**Source:** [App/site/product name and what it does]
+**Why it's relevant:** [1-2 sentences connecting this to the project brief]
+**What to take:** [The specific element or quality to learn from]
+**What to leave:** [What doesn't apply — this prevents wholesale copying]
+**Taste alignment:** [How it connects to the user's taste profile]
+**Layer:** Visual / Interaction / Emotional
+```
+
+### Step 4: Cross-Domain Connections
+
+The best inspiration often comes from outside the project's domain. Actively seek cross-domain references:
+
+| Project Domain | Look At |
+|---------------|---------|
+| Healthcare | Meditation apps (calm), fitness apps (motivation), journaling apps (reflection) |
+| Finance | Productivity tools (clarity), weather apps (data viz), news apps (hierarchy) |
+| Education | Games (engagement), music apps (progression), social apps (community) |
+| E-commerce | Editorial sites (storytelling), gallery apps (browsing), travel apps (discovery) |
+| Enterprise | Consumer apps (polish), design tools (power + clarity), documentation sites (wayfinding) |
+
+Don't force connections — but don't limit yourself to competitors either.
+
+### Step 5: Present the Board
+
+Present inspiration to the user and the design-lead as a curated collection:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  INSPIRATION BOARD
+  For: [Project Name]
+  Feel: [target adjectives]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  VISUAL DIRECTION
+  ◆ [Reference 1] — [what to take]
+  ◆ [Reference 2] — [what to take]
+
+  INTERACTION PATTERNS
+  ◆ [Reference 3] — [what to take]
+  ◆ [Reference 4] — [what to take]
+
+  EMOTIONAL TONE
+  ◆ [Reference 5] — [what to take]
+
+  CROSS-DOMAIN WILD CARD
+  ◆ [Reference 6] — [unexpected connection]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Does any of this resonate? I can dig deeper
+  into any direction or find more references.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 6: Refine Based on Response
+
+The user's reaction to inspiration is a powerful taste signal:
+
+| Reaction | What to Do | Taste Signal |
+|----------|-----------|--------------|
+| "Love that" | Dig deeper into similar references | Strong positive — record in design-memory |
+| "Not quite" | Ask what's off — too bold? too safe? wrong tone? | Soft negative — refine search |
+| "That but calmer" | The direction is right, the intensity is wrong | Record the adjustment as a taste nuance |
+| "None of these" | Go back to Step 1 and redefine the feel | The inspiration brief needs rewriting |
+| "Number 3, but for the layout, not the colour" | User is compositing — they see the design in pieces | Record which layers resonate separately |
+
+After refinement, update the inspiration brief with what resonated and pass it to design-lead as part of their brief.
+
+## Integration With Taste Profile
+
+Inspiration is driven by **this project's** direction — the brief and the live taste calibration from `design-taste` — not by the cross-project design record. The `design-memory` record is observational and is **not** used to pre-filter or steer references; doing so would silently apply one project's habits to another. (If the user themselves says "I usually avoid gradients," that's live direction for this project — honour it because they said it now, not because a record predicted it.)
+
+You may still **record** new signals into `design-memory` as observations after the fact (see below) — that's watching, not steering.
+
+## Integration
+
+- **Called by:** `design-discovery` (to set visual direction), `design-strategy` (for positioning references), `using-designpowers` (when user requests inspiration)
+- **Calls:** `design-memory` (only to record new observations after the fact — never to read constraints that steer the scouting)
+- **Hands off to:** `design-lead` (with curated references as visual brief), `design-strategist` (with emotional/UX references)
+- **Pairs with:** `design-memory`, `design-debate` (inspiration can trigger a debate on direction)
+- **Updated by:** User reactions — every "love it" or "not for me" is a taste data point
+
+## Anti-Patterns
+
+| Pattern | Why It Fails |
+|---------|-------------|
+| Dumping 20 references without curation | Overwhelms. 5 excellent references with clear "what to take" beats 20 screenshots |
+| Only looking at competitors | Competitors solve the same problem the same way. Cross-domain references unlock fresh approaches |
+| Showing inspiration that violates accessibility | A beautiful reference with 2:1 contrast ratios is not inspiration — it's a cautionary tale. Flag accessibility issues in references |
+| Copying instead of being inspired | Inspiration means "take the quality, not the pixels." Always specify what to take and what to leave |
+| Ignoring this project's stated direction | If the user has said (now) they want a calm, gradient-free look, showing gradient-heavy references wastes their time. Drive from `design-taste`, not from the cross-project record |
+| Presenting without "what to take" | A reference without a clear lesson is decoration. Every reference needs a reason |

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/interaction-design/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: interaction-design
+description: "Use when designing states, transitions, animations, error handling, loading patterns, feedback, or any behaviour that responds to user action — ensures interactions are perceivable, operable, and inclusive"
+---
+
+# Interaction Design
+
+Interactions are promises. Every button says "click me and something will happen." Every loading spinner says "wait, it is coming." This skill ensures those promises are kept for everyone, regardless of how they interact with the interface.
+
+## When to Use
+
+- Designing component states (default, hover, active, focus, disabled, error)
+- Creating transitions or animations
+- Handling errors, empty states, or edge cases
+- Designing loading and progress patterns
+- Defining feedback mechanisms (success, warning, error confirmations)
+- Designing gesture or touch interactions
+
+## Process
+
+### Step 1: Map All States
+
+For every interactive element, define:
+
+| State | Visual | Screen Reader | Keyboard | Touch |
+|-------|--------|--------------|----------|-------|
+| Default | [appearance] | [announcement] | [behaviour] | [behaviour] |
+| Hover | [appearance] | n/a | n/a | n/a |
+| Focus | [appearance + focus ring] | [announcement] | [how to reach] | n/a |
+| Active/Pressed | [appearance] | [announcement] | [trigger key] | [gesture] |
+| Disabled | [appearance, not just greyed] | [announcement + reason] | [skip in tab order?] | [behaviour] |
+| Error | [appearance + message] | [announcement + guidance] | [focus moved?] | [behaviour] |
+| Loading | [appearance] | [live region update] | [interaction blocked?] | [behaviour] |
+| Success | [appearance] | [announcement] | [next focus target] | [behaviour] |
+
+### Step 2: Design Feedback Patterns
+
+Every user action deserves a response. Map the feedback:
+
+**Immediate feedback (< 100ms):**
+- Visual state change on interaction (button press, toggle flip)
+- Must be perceivable without relying on colour alone
+
+**Short wait feedback (100ms - 1s):**
+- Loading indicator or skeleton screen
+- ARIA live region announcement: "Loading..."
+
+**Long wait feedback (> 1s):**
+- Progress indicator with estimated time or progress percentage
+- Ability to cancel or navigate away
+- ARIA live region updates at intervals
+
+**Completion feedback:**
+- Clear success or error state
+- Screen reader announcement of outcome
+- Logical next focus target
+
+### Step 3: Error Handling
+
+Errors are not edge cases — they are guaranteed states. Design for them:
+
+1. **Prevention first** — inline validation, clear constraints, sensible defaults
+2. **Clear identification** — what went wrong, in plain language
+3. **Specific guidance** — what the person should do next
+4. **Accessible delivery** — errors announced to screen readers, focus moved to the error, not just a colour change
+5. **Recovery path** — preserve user input, allow correction without starting over
+
+Error message format: **[What happened] + [What to do about it]**
+- Yes: "That email address is already registered. Try signing in instead, or use a different email."
+- No: "Error: invalid input"
+
+### Step 4: Animation and Motion
+
+Animations serve a purpose or they serve nobody:
+
+**When to animate:**
+- To show a relationship between elements (a panel sliding in from its trigger)
+- To maintain spatial orientation (a page transition showing direction)
+- To provide feedback (a subtle bounce on a successful action)
+
+**When NOT to animate:**
+- Decoration without function
+- Anything that delays the user from completing their task
+- Anything that loops indefinitely
+
+**Inclusive motion:**
+- Respect `prefers-reduced-motion` — always provide a reduced or no-motion alternative
+- Keep durations short: 150-300ms for micro-interactions, 300-500ms for transitions
+- Avoid parallax, auto-playing video, flashing content (3 flashes per second maximum per WCAG)
+- Provide pause/stop controls for any animation longer than 5 seconds
+
+### Step 5: Gesture and Input Design
+
+If the design includes gesture interactions:
+- Every gesture must have a non-gesture alternative (button, keyboard shortcut)
+- Swipe actions must be discoverable without trial-and-error
+- Drag-and-drop must have a keyboard-accessible alternative
+- Touch targets: 44x44px minimum, with adequate spacing between targets
+
+### Step 6: Document the Interaction Spec
+
+For each interaction, document:
+- Trigger (what initiates the interaction)
+- Behaviour (what happens, step by step)
+- States (all states the element passes through)
+- Feedback (what the user perceives at each stage)
+- Accessibility (screen reader announcements, keyboard behaviour, motion reduction)
+
+## Integration
+
+- **Called by:** `writing-design-plans` (as part of plan execution)
+- **Pairs with:** `ui-composition` (visual states), `cognitive-accessibility` (interaction complexity), `accessible-content` (error messages)
+- **Reviewed by:** `designpowers-critique`
+
+## Red Flags
+
+| Flag | Response |
+|------|----------|
+| Component with only default and hover states | Map ALL states including focus, error, loading, disabled |
+| Animation without prefers-reduced-motion support | Add motion reduction. This is not optional |
+| Error state that only changes colour | Add text, icon, and screen reader announcement |
+| Gesture without alternative input method | Add keyboard and/or button alternative |

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/motion-choreography/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: motion-choreography
+description: "Use when designing animation sequences, page transitions, micro-interactions, loading states, or any motion that communicates meaning — ensures motion is purposeful, performant, and safe for motion-sensitive users"
+---
+
+# Motion Choreography
+
+Motion is communication. Every animation answers a question the user didn't know they had. If it doesn't answer one, cut it.
+
+## The Three Questions
+
+Before adding any animation:
+1. **What changed?** — the animation makes it visible
+2. **What should I look at next?** — directs attention
+3. **How are these related?** — shows spatial/hierarchical relationship
+
+Can't answer at least one? The animation is decoration. Cut it.
+
+## Duration Guide
+
+| Context | Duration |
+|---------|----------|
+| Micro-interaction (button, toggle) | 100-200ms |
+| State change (card expand, tab) | 200-300ms |
+| Screen transition | 250-400ms |
+| Complex choreography | 400-700ms total |
+
+Nothing over 1 second unless it's a loading indicator.
+
+## Easing Reference
+
+| Context | Easing |
+|---------|--------|
+| Entering | ease-out (decelerate) |
+| Leaving | ease-in (accelerate) |
+| State change | ease-in-out |
+| Micro-interaction | spring (stiffness 300-500) |
+
+## Stagger Patterns
+
+- 50-80ms delay between items
+- Maximum 5 items staggered, rest appear instantly
+- Follow reading order
+- Reveal hierarchy — important items first
+
+## Reduced Motion
+
+`prefers-reduced-motion: reduce` means reduce, not remove.
+
+| Standard | Reduced alternative |
+|----------|-------------------|
+| Slide in | Fade in |
+| Scale with bounce | Instant appearance |
+| Parallax scroll | Static |
+| Staggered reveal | Simultaneous fade |
+| Continuous pulse | Static state |
+
+**Every animation must have a reduced-motion alternative. No exceptions.**
+
+## What NOT to Animate
+
+- Text colour changes (photosensitive risk)
+- Layout properties in performance paths (use transform)
+- Anything that delays task completion
+- Decorative loops without user control
+
+## Performance
+
+Only animate: `transform`, `opacity`, `filter`. These are GPU-composited.
+
+## What You Deliver
+
+- Animation specs with durations, easings, triggers
+- Reduced-motion alternatives for every animation
+- Performance annotations
+- Sequence diagrams for complex choreography
+
+## Integration
+
+- **Informed by:** `design-lead`, `interaction-design`
+- **Feeds into:** `motion-designer` agent, `accessibility-reviewer`, `design-builder`

package/packages/shared-skills/skills/frontend/references/designpowers/vendor/skills/research-planning/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: research-planning
+description: "Use when user needs are unclear, assumptions need validation, or the design brief identifies gaps in understanding — plans what to learn, which methods to use, and from whom"
+---
+
+# Research Planning
+
+Research is how we replace assumptions with evidence. This skill structures what you need to learn before committing to a design direction.
+
+## When to Use
+
+- The design brief identifies unknowns about users, context, or behaviour
+- The team is making decisions based on assumptions rather than evidence
+- A design is being created for a new audience or unfamiliar context
+- Stakeholders disagree about user needs
+
+## Process
+
+### Step 1: Identify Knowledge Gaps
+
+Review the design brief and list:
+- What do we **know** about the people who will use this? (Evidence-backed)
+- What do we **assume**? (Believed but unverified)
+- What do we **not know**? (Acknowledged gaps)
+
+Present this to the user. Assumptions and unknowns become research questions.
+
+### Step 2: Frame Research Questions
+
+Convert gaps into answerable questions. Good research questions are:
+- **Specific** — "How do users with screen readers navigate multi-step forms?" not "Is the form accessible?"
+- **Observable** — focused on behaviour, not opinion
+- **Actionable** — the answer will change a design decision
+
+Aim for 3-5 research questions. More than that means you need to narrow scope.
+
+### Step 3: Select Methods
+
+Match methods to questions:
+
+| Question Type | Recommended Methods |
+|--------------|-------------------|
+| "What do people currently do?" | Journey mapping, diary studies, contextual inquiry |
+| "Why do people struggle with X?" | Usability testing, think-aloud protocols |
+| "What do people need?" | Interviews, jobs-to-be-done analysis |
+| "Which approach works better?" | A/B testing, preference testing, card sorting |
+| "How does our offering compare?" | Competitive analysis, heuristic evaluation |
+| "Who are we designing for?" | Persona development, ability spectrum mapping |
+
+### Step 4: Plan for Inclusion
+
+Every research plan must address:
+- **Participant diversity** — include people with disabilities, different ages, different technical literacy, different languages
+- **Method accessibility** — ensure research methods themselves are accessible (e.g., interview formats that work for people with communication differences)
+- **Situational contexts** — include scenarios of stress, distraction, low bandwidth, unfamiliar environments
+
+### Step 5: Write the Research Plan
+
+```markdown
+# Research Plan: [Topic]
+
+## Research Questions
+1. [Question]
+2. [Question]
+3. [Question]
+
+## Methods
+| Method | Questions Addressed | Participants | Timeline |
+|--------|-------------------|-------------|----------|
+| [Method] | Q1, Q2 | [Who and how many] | [When] |
+
+## Inclusion Considerations
+[How participant diversity and method accessibility will be ensured]
+
+## Expected Outputs
+[What deliverables this research will produce — personas, journey maps, findings report]
+
+## Decision Points
+[Which design decisions this research will inform]
+```
+
+Save to: `docs/designpowers/research/YYYY-MM-DD-<topic>-plan.md`
+
+### Step 6: User Review
+
+Present the plan. Confirm scope, methods, and timeline are realistic.
+
+## Integration
+
+- **Called by:** `design-discovery`
+- **Calls:** `inclusive-personas` (when persona development is a research output)
+- **Pairs with:** `design-strategy` (research informs strategy)
+
+## What This Skill Does NOT Do
+
+This skill plans research — it does not execute it. Execution happens with real people in the real world. The plan ensures that when research happens, it is structured, inclusive, and actionable.