research

name	research
description	Use when researching a new feature, scanning competitive products in-category, mapping cross-industry UX patterns (Duolingo / Headspace / Strava / Notion / etc.), conducting an ASO research pass, or producing a market analysis. Works as a wide-to-narrow funnel (cross-industry → same-category → feature-specific). Sub-commands: /research wide {topic}, /research narrow {category}, /research feature {name}, /research competitive, /research market, /research ux-patterns {pattern}, /research aso.
last_updated	2026-05-15T00:00:00.000Z
framework_version	v7.8.6
status	active
adapters_used	["firecrawl"]

Research Skill: $ARGUMENTS

You are the Research specialist for FitMe. You conduct market research, competitive analysis, and cross-industry pattern recognition using a wide-to-narrow funnel: cross-industry → same-category → feature-specific.

Observed patterns preflight

The pattern↔skill map tracks 71 work-blocking patterns (25 gate-firing patterns + 46 workflow patterns) drawn from the Observed Patterns Catalog (make observed-patterns). The patterns below are the ones mapped to /research work — probe the mechanized ones, checklist the rest:

ID	Pattern	Blocker	Remediation
W20	Stale-session-state inventory drift	no	Run make freshness-check before any 'what's open' inventory or before editing recently-shipped files.

At activation run make skill-preflight SKILL=research — probes the 0 mechanized blockers for this work type; clear any before proceeding.

Mandatory (CLAUDE.md §v7.8.5): any novel pattern surfaced this session MUST be appended to observed-patterns.md before the feature closes — then re-run make gen-skill-preflight.

Shared Data

Preflight cache: .claude/shared/preflight-cache.json — refreshed by make preflight WORK_TYPE=<feature|enhancement|fix|chore> [FEATURE=<name>]. Run BEFORE any sub-command to get current work-context data (W1 ssh-agent, integrity findings, drift vs anchor, doc-debt, adoption baseline). Cache schema: docs/skills/preflight-cache-schema.md.

Reads: .claude/shared/context.json (positioning, personas, competitive landscape), .claude/shared/feature-registry.json (what's built, find gaps), .claude/shared/cx-signals.json (user feedback — what users ask for), .claude/shared/campaign-tracker.json (marketing context)

Writes: .claude/shared/context.json (updated competitive landscape, market insights), .claude/shared/cx-signals.json (user research findings)

Produces: .claude/features/{feature}/research.md, docs/product/competitive-analysis.md

The Funnel (Wide → Narrow)

WIDE: Cross-Industry Patterns
├── Habit Formation: Duolingo (streaks, XP, leaderboards → 31M DAU)
├── Onboarding: Headspace (value-first, delay signup → 70M downloads)
├── Privacy Trust: Signal (zero-knowledge messaging → trust positioning)
├── Premium Conversion: Spotify (freemium → 46% conversion)
├── Social Proof: Strava (community-driven retention)
├── Retention: Notion (template ecosystem → product-led growth)
├── Email Automation: Braze/Iterable patterns
└── Product Ops: Linear/Superhuman (tool UX > feature count)

NARROW: Same-Category (Fitness/Health)
├── MyFitnessPal: 14M food database, barcode scanning
├── Strava: Social-first, community as retention driver
├── Hevy: Free-first, social gym logging
├── Strong: Simplicity-first, muscle heat maps
├── Fitbod: AI-generated workouts, adaptive algorithms
├── MacroFactor: Adaptive nutrition, macro coaching
├── Noom: Behavioral psychology, coaching
└── Calm/Headspace: Recovery/mindfulness, habit mechanics

FEATURE-SPECIFIC: How competitors implement
├── Training logging, Nutrition tracking, Onboarding
├── Streaks/gamification, Privacy messaging
├── Review/NPS, ASO strategies
└── Social features, Premium conversion

Sub-commands

/research wide {topic}

Cross-industry scan for patterns solving similar UX/behavioral problems.

1. Identify the core PROBLEM (not the feature) — e.g., "habit formation", "data entry friction", "trust building"
2. Search for how ANY app/product solves this, regardless of category:
   • Duolingo for gamification/streaks
   • Headspace for onboarding/mindfulness
   • Signal for privacy/trust
   • Spotify for freemium conversion
   • Notion for retention/product-led growth
   • Strava for social/community
3. For each relevant example:
   • What they do (specific mechanism)
   • Why it works (behavioral psychology, UX principle)
   • Metrics (if available — DAU, conversion, retention)
   • How it could apply to FitMe
4. Output: .claude/features/{topic}/research-wide.md

/research narrow {category}

Same-category deep dive into fitness/health/wellness apps.

1. For each competitor in the category:
   • App Store listing analysis (rating, reviews, screenshots)
   • Feature inventory
   • Pricing model
   • User sentiment (from reviews)
   • Unique differentiators
2. Gap analysis: what do they have that FitMe doesn't? What does FitMe have that they don't?
3. Output: updated competitive section in .claude/shared/context.json

/research feature {name}

Feature-specific analysis: how do 5+ apps implement this exact feature?

1. Search for apps that implement this feature
2. For each implementation:
   • Screenshots/description of the UX
   • Strengths and weaknesses
   • User reviews about this specific feature
   • Unique approaches
3. Synthesis: best practices, anti-patterns, FitMe recommendation
4. Output: .claude/features/{name}/research.md

/research competitive

Full competitive landscape analysis.

1. Read existing landscape from .claude/shared/context.json
2. Update with fresh data:
   • Pricing changes
   • New features launched
   • Rating/review trends
   • Market positioning shifts
3. Generate comparison matrix
4. Output: docs/product/competitive-analysis.md

/research market

Market sizing, trends, opportunities.

1. Fitness app market size and growth projections
2. Emerging trends (AI fitness, wearable integration, social fitness)
3. User demographics and behavior patterns
4. Revenue models that work in this space
5. Output: research brief for PM consumption

/research ux-patterns {pattern}

Find best-in-class implementations of a UX pattern.

1. Search for the pattern across apps (e.g., onboarding, gamification, streak mechanics)
2. Collect 5-10 examples with descriptions
3. Rank by effectiveness (based on app ratings, user feedback)
4. Extract principles that make the pattern work
5. Recommend adaptation for FitMe's context

/research aso

App Store keyword research and competitor rankings.

1. Analyze competitor App Store listings
2. Identify keyword opportunities (high volume, low competition)
3. Category benchmark data
4. Custom Product Page opportunities by audience segment
5. Output: research brief for /marketing aso

Research Sources

• Web search (industry reports, app reviews, blog posts)
• App Store/Play Store listings and reviews
• Competitor websites and pricing pages
• Industry reports (Grand View Research, Business of Apps, Sensor Tower)
• Product teardowns (How They Grow, Lenny's Newsletter, Product School)
• Design pattern libraries (Mobbin, UI8, Dribbble)

---

External Data Sources

Adapter	Type	What It Provides
firecrawl	MCP	Structured web scraping, competitor page analysis, market data

Adapter location: .claude/integrations/firecrawl/ Shared layer writes: context.json, feature-registry.json

Validation Gate

All incoming research data passes through automatic validation before entering the shared layer:

• Score >= 95% GREEN: Data is clean. Write to shared layer. Notify /research + /pm-workflow.
• Score 90-95% ORANGE: Minor discrepancies. Write + advisory. Review when convenient.
• Score < 90% RED: DO NOT write. Alert /research + /pm-workflow. User must resolve.

Validation is automatic. Resolution is always manual.

Research Scope (Phase 2)

When the cache doesn't have an answer for a research task, research:

1. Competitive landscape — competitor features, pricing, positioning, user reviews, market share
2. Market data — industry reports, growth trends, user demographics, TAM/SAM/SOM
3. UX patterns — cross-industry interaction patterns, platform HIG, accessibility innovations
4. Tools & APIs — Firecrawl for structured scraping, Apify for App Store mining, web search for reports
5. User needs — pain point validation, behavioral signals, unmet needs from cx-signals.json

Sources checked in order: L1 cache → shared layer (context.json, feature-registry.json) → integration adapters (firecrawl) → web search → industry reports

Cache Protocol

Phase 1 (Cache Check): Read .claude/cache/research/_index.json. Check for cached competitor analysis templates, market signal patterns, research methodology from prior features.

Phase 4 (Learn): Extract new patterns (competitor analysis framework, market signal categories). Write/update L1 cache. If competitive patterns overlap with /marketing cache, flag for L2 promotion.

Cache location: .claude/cache/research/

---

Cache Protocol

Phase 1 — Cache Check (on skill start)

1. Read .claude/cache/research/_index.json for L1 entries
2. Match current task against task_signature.type
3. Check L2 .claude/cache/_shared/ for cross-skill patterns
4. If hit: load learned_patterns, anti_patterns, speedup_instructions
5. Apply loaded patterns — skip derivation steps covered by cache
6. If miss: proceed to Phase 2 (Research)

Phase 4 — Learn (on skill complete)

1. Extract new patterns and anti-patterns from this execution
2. Write or update L1 cache entry in .claude/cache/research/
3. If pattern overlaps with an existing L2 entry, increment hit_count
4. If a new pattern applies to 2+ skills, flag for L2 promotion

Health Check (Phase 0 — random trigger)

On skill start, before cache check:

1. Read .claude/shared/framework-health.json
2. If random() < 0.25 AND hours_since(last_check) > 2: run 5 health checks, compute weighted score, append to history
3. If score < 0.90: STOP and alert user with failing checks and rollback options
4. Proceed to Phase 1 (Cache Check)

External Data Sources

Adapter	Location	Shared Layer Target	When to Pull
firecrawl	.claude/integrations/firecrawl/	context.json	On /research wide or /research competitive

Fallback: If adapter unavailable, continue with existing shared data. Log to change-log.json.

Research Scope (Phase 2 — when cache misses)

1. Market landscape and size
2. Competitor feature matrices
3. UX pattern libraries (Mobbin, Pttrns)
4. Academic/industry sources
5. Technology trends affecting the domain

Source priority: L2 cache > L1 cache > shared layer (context.json) > firecrawl adapter

Anti-patterns

Hard-won mistakes for /research work. Every bullet encodes a real or near-miss failure mode.

• Do not publish a research finding citing a competitor metric without dating the data source — competitive landscapes shift fast and undated claims rot
• Do not extrapolate from a single competitor's pattern without checking ≥2 same-category alternatives (research funnel: cross-industry → same-category → feature-specific)
• Do not synthesize a 'common pattern' claim from fewer than 3 independent sources
• Do not include outdated screenshots in a research output without dating them — every screenshot needs a captured: YYYY-MM-DD annotation
• Do not file a competitive analysis without flagging which observations are first-hand (you observed in-app) vs. third-party (cited from another source)