---
name: gamification-engine
description: "Engenheiro de gameficação humano-cêntrica completo. Use para projetar, implementar, auditar e iterar sistemas de engajamento que criam hábito diário saudável: Octalysis 8 Core Drives, Hook Model, Fogg Behavior Model, SDT, Bartle player types; sistemas de XP/níveis/streaks/quests/badges/coleções/leaderboards de liga; economia virtual; avatar e narrativa; copy de notificações alegres e divertidas (push, in-app, e-mail) com timing inteligente; integração FCM/OneSignal/Expo Notifications; telemetria GA4/Clarity/Amplitude; regras Firestore anti-cheat; A/B testing; guardrails éticos contra dark patterns; e MCPs gratuitos úteis para o desenvolvimento. Aciona quando o usuário pede para gameficar app, criar hábito, aumentar retenção D1/D7/D30, escrever copy de notificação, projetar onboarding emocionante, montar streak, definir XP/níveis ou auditar gameficação existente."
argument-hint: "Produto + público + comportamento-alvo + métrica-norte + stack + canais (push/email/in-app) + estágio (zero/MVP/produção)."
---
# Gamification Engine — Engenharia de Engajamento Humano-Cêntrico
Skill operacional para construir sistemas de gameficação que **fazem o usuário se sentir bem consigo mesmo todo dia** e, como consequência, escalam o produto.
## Quando Usar
- Aumentar retenção D1/D7/D30, DAU/MAU stickiness, dias-ativos/semana.
- Criar hábito diário em apps de saúde, finanças, educação, produtividade, fitness.
- Projetar onboarding que emociona em vez de tutoriar.
- Escrever copy de push/in-app/e-mail que encanta sem irritar.
- Auditar gameficação existente (mapa Octalysis Level 1).
- Definir economia de XP, moedas, recompensas, streaks com freeze.
- Implementar leaderboard de liga (estilo Duolingo) sem desmotivar 95% da base.
- Decidir entre OneSignal, FCM, Expo Notifications, Customer.io, Braze.
- Combater churn por quebra de streak.
**Não use para**: tarefas puramente técnicas sem componente de comportamento (refatoração, debug de bug não-relacionado a engajamento, configuração de CI). Para essas, agente padrão.
## Procedimento Padrão (em 7 etapas)
### Etapa 1 — Discovery
Antes de propor qualquer mecânica, descubra:
| Pergunta | Por que importa |
|---|---|
| Qual é o **comportamento-âncora** repetível diário? | Hábito = ação pequena × frequência × recompensa |
| Quem é o **público** (idade, motivação, contexto de uso)? | Define tom de voz, tipos Bartle dominantes |
| Qual é a **métrica-norte**? | Retenção D7? DAU? Dias-com-ação? Tudo gira em torno dela |
| Quais **canais** estão disponíveis? | Push, in-app, e-mail, SMS — cada um tem regras |
| Qual a **stack**? | RN/Expo? Web? Firebase? Supabase? Define as ferramentas |
| Qual o **estágio**? | Zero (greenfield), MVP (sem dados), produção (tem analytics)? |
| Há **restrições éticas/regulatórias**? | LGPD, COPPA (crianças), regulação financeira/saúde |
Se o produto está em produção, **antes de opinar consulte dados reais** via Microsoft Clarity MCP (`query-analytics-dashboard`, `list-session-recordings`) para ver onde os usuários frustram, abandonam, raivam.
### Etapa 2 — Mapa Octalysis Level 1
Para cada uma das 8 Core Drives, classifique o produto em: **Forte / Médio / Fraco / Ausente**, e justifique com features concretas. Veja [octalysis-template.md](./references/octalysis-template.md) para o template completo.
```
1. Significado Épico & Vocação [F/M/F/A] — feature: ...
2. Desenvolvimento & Realização [F/M/F/A] — feature: ...
3. Empoderamento & Feedback [F/M/F/A] — feature: ...
4. Posse & Possessão [F/M/F/A] — feature: ...
5. Influência Social & Pertencimento[F/M/F/A] — feature: ...
6. Escassez & Impaciência [F/M/F/A] — feature: ...
7. Imprevisibilidade & Curiosidade [F/M/F/A] — feature: ...
8. Perda & Evitação [F/M/F/A] — feature: ...
```
Identifique as 2-3 drives mais fracas que, se reforçadas, mais movem a métrica-norte.
### Etapa 3 — Roadmap em 3 Horizontes
**Horizonte 1 (1-2 semanas) — Quick wins de baixo custo, alto impacto emocional:**
- Substituir copy de notificações por versões alegres com mascote (ver [notification-copy-library.md](./references/notification-copy-library.md)).
- Adicionar microcelebrações em ações já existentes (haptic + lottie + texto encorajador).
- Tela de "você conseguiu!" após primeira ação-âncora do dia.
- Permission priming customizado antes do prompt nativo de push.
**Horizonte 2 (1-2 meses) — Loop de hábito completo:**
- Streak com freeze (1-2/mês grátis) + repair pago.
- 3 quests diárias (1 trivial < 2min, 1 média, 1 desafiadora) com reroll.
- Sistema de XP e níveis (curva exponencial atenuada — ver [xp-curve.md](./references/xp-curve.md)).
- Liga semanal (10 ligas, top 3 sobem, bottom 3 descem, proteção shield para últimos 5).
- Re-engajamento automático D1/D3/D7/D14/D30.
- Telemetria de eventos críticos (ver [analytics-events.md](./references/analytics-events.md)).
**Horizonte 3 (3-6 meses) — Endgame e profundidade:**
- Avatar customizável com itens ganhos por progresso.
- Economia virtual de moeda soft (gemas) e itens consumíveis (streak freeze, XP boost).
- Coleções (cards/troféus/álbum), com 2-3% raros que ativam Curiosidade.
- Sistema social: amigos, grupos, mentor, desafios duplos.
- Narrativa progressiva (capítulos desbloqueados por níveis).
- Eventos sazonais limitados (Halloween, Natal, aniversário do app) com recompensas exclusivas.
### Etapa 4 — Implementação
#### 4.1 Schema de dados (Firestore)
```typescript
// users/{uid}
{
uid: string,
displayName: string,
level: number,
xp: number, // total acumulado
xpToNextLevel: number, // calculado
streak: { current: number, longest: number, lastActiveDate: string, freezesAvailable: number },
coins: number, // moeda soft
gems: number, // moeda hard/rara
league: { tier: number, position: number, weekId: string },
badges: string[], // IDs de conquistas
notificationPrefs: { push: boolean, quietHoursStart: string, quietHoursEnd: string, frequency: 'low'|'normal'|'high' },
createdAt: Timestamp,
lastActiveAt: Timestamp,
optimalNotificationHour: number, // aprendido pelo backend
}
// users/{uid}/quests/{questId}
{ type: 'daily'|'weekly'|'special', goal: number, progress: number, reward: { xp, coins, badge? }, completedAt? }
// users/{uid}/events/{eventId} // log para anti-cheat
{ type, value, timestamp, sessionId, validated: boolean }
```
**Regras de segurança críticas** (anti-cheat): usuário só lê o próprio doc; XP/coins/level **só são escritos por Cloud Function** validando origem da ação. Ver [firestore-rules-template.md](./references/firestore-rules-template.md).
#### 4.2 Cloud Functions essenciais
- `awardXP(userId, source, amount)` — valida source contra catálogo, debita rate limit, escreve.
- `checkStreak(userId)` — disparada por scheduler 00:01 do timezone do usuário; quebra ou usa freeze.
- `assignDailyQuests(userId)` — gera 3 quests baseadas em histórico (algoritmo: 1 do tipo que ele já faz, 1 que ele evita, 1 social).
- `weeklyLeagueResolver()` — scheduled segunda 00:00 UTC, promove/rebaixa, distribui recompensas.
- `sendSmartNotification(userId, type)` — escolhe copy random de pool, respeita quiet hours e cap diário, registra envio.
#### 4.3 Componentes RN/Expo
- `` — animação suave do enchimento (Reanimated 3, UI thread, withSpring).
- `` — chama lottie diferente por faixa (1-3 / 4-7 / 8-30 / 31-100 / 100+).
- `` — confete + lottie + haptic Heavy + som opcional.
- `` — checklist com progresso, botão de reroll (1/dia grátis).
- `` — lista virtualizada, posição do usuário sempre visível, animação na promoção.
Bibliotecas recomendadas:
- `react-native-reanimated@^3` — animações 60fps na UI thread
- `lottie-react-native` — celebrações leves (< 50KB cada Lottie)
- `react-native-confetti-cannon` — confete em vitórias maiores
- `expo-haptics` — toques físicos sincronizados com celebrações
- `react-native-sound` ou `expo-av` — sons opcionais (sempre com mute global)
- `expo-notifications` + `@react-native-firebase/messaging` — push
Sempre respeite `AccessibilityInfo.isReduceMotionEnabled()` — se ligado, troque animações por fade simples.
### Etapa 5 — Sistema de Notificações
Consulte [notification-system.md](./references/notification-system.md) para arquitetura completa, e [notification-copy-library.md](./references/notification-copy-library.md) para 100+ variações de copy em PT-BR prontas para usar.
Regras-chave:
- 1-2 push/dia máximo. 3 só com opt-in explícito.
- Quiet hours 22h-8h padrão.
- Aprenda o horário ótimo do usuário em 7 dias e dispare lá.
- Pool mínimo de 30 variações por tipo crítico.
- Frequency capping global e por tipo.
- Decay automático: 3 ignoradas seguidas → reduz frequência.
- A/B test contínuo de copy + horário + CTA.
### Etapa 6 — Telemetria e Medição
Eventos mínimos obrigatórios (GA4 + Amplitude/Mixpanel) — ver lista completa em [analytics-events.md](./references/analytics-events.md):
`onboarding_step_completed`, `habit_action_completed`, `xp_awarded`, `level_up`, `streak_extended`, `streak_lost`, `streak_freeze_used`, `quest_assigned`, `quest_completed`, `badge_unlocked`, `league_promoted`, `league_demoted`, `notification_sent`, `notification_opened`, `notification_dismissed`, `push_permission_requested`, `push_permission_granted`, `app_opened_from_push`.
Dashboards essenciais:
- Funil de onboarding (quantos chegam à primeira ação-âncora).
- Curva de retenção D1/D7/D30 por cohort de instalação.
- Distribuição de streak (histograma — onde está o gargalo).
- Saúde de notificações: open rate por tipo, opt-out rate, denúncias.
- Liga: distribuição de usuários por tier, rotatividade semanal.
### Etapa 7 — Guardrails Éticos
Antes de entregar, confira a checklist em [ethical-guardrails.md](./references/ethical-guardrails.md). Resumo:
- ✅ Streak tem mecanismo de recuperação?
- ✅ Push tem opt-out fácil de 1 toque?
- ✅ Quiet hours respeitadas?
- ✅ Não há FOMO falso ou escassez inventada?
- ✅ Linguagem positiva, nunca culpabilizadora?
- ✅ Crianças (<13) não expostas a recompensa variável tipo loot box?
- ✅ Acessibilidade: reduce motion, mute, contraste, screen reader?
- ✅ LGPD: consentimento granular + exportação + deleção?
- ✅ Telemetria não vaza PII?
## MCPs Gratuitos Úteis
Para acelerar desenvolvimento de gameficação, considere instalar (todos têm tier gratuito):
| MCP | Para que serve em gameficação |
|---|---|
| `microsoft.clarity-mcp-server` | Ver gravações reais de usuários frustrados, rage clicks, dead clicks. Ouro para diagnóstico Octalysis. |
| `upstash/context7-mcp` | Docs sempre atualizadas de FCM, Expo Notifications, OneSignal, Firebase, Reanimated. |
| `modelcontextprotocol/server-sequential-thinking` | Quebrar design de loops complexos em passos verificáveis. |
| `modelcontextprotocol/server-memory` | Persistir personas, histórico de decisões de design, hipóteses A/B através de sessões. |
| `modelcontextprotocol/server-time` | Cálculos de timezone para streaks e notificações por região. |
| `modelcontextprotocol/server-fetch` | Puxar conteúdo de blogs/case studies de gameficação ao vivo. |
| `modelcontextprotocol/server-filesystem` | Manipular assets Lottie, JSONs de quests, catálogos de copy. |
| `chrome-devtools` (DevTools MCP) | Auditar performance de animações web, Core Web Vitals em telas de celebração. |
| `mcp-server-github` (`@modelcontextprotocol/server-github`) | Buscar implementações de referência open-source (Duolingo-likes, habit trackers). |
| `brave-search-mcp-server` | Pesquisar last-mile (best practices, novos cases). |
| `posthog-mcp` (community) | Funis, retenção, A/B test programático sem sair do agente. |
| `notion-mcp` ou `linear-mcp` | Documentar roadmap de gameficação direto no PM tool. |
Instalação típica via VS Code `mcp.json` — peça a este agente para configurar quando precisar.
## Anti-Padrões (Nunca Faça)
- **Pontos sem desafio**: badge fácil demais perde valor; cuidado com inflação.
- **Leaderboard global aberto**: desmotiva 95% da base. Use ligas pequenas (10-30 pessoas).
- **Streak sem freeze**: o usuário viaja, pega gripe, perde 60 dias e desinstala.
- **Push genérico**: "Não esqueça do app!" mata permission. Prefira específico, contextual, com nome.
- **Recompensa variável extrema**: vira gambling. Para crianças, nunca. Para adultos, com cuidado.
- **Onboarding longo demais**: cada tela perde 20% dos usuários. Máximo 4-5 telas até primeira ação-âncora.
- **Mecânica sem evento de telemetria**: você não vai conseguir provar que funciona.
- **Copy condescendente**: "Que bonitinho, você fez seu exercício!" — soa falso. Prefira: "3 dias seguidos. Tá voando."
- **Black Hat empilhado**: escassez + perda + imprevisibilidade ao mesmo tempo = ansiedade, não engajamento.
## Referências (Progressive Disclosure)
Carregue conforme a necessidade da tarefa atual:
- [octalysis-template.md](./references/octalysis-template.md) — Template de auditoria das 8 Core Drives
- [notification-system.md](./references/notification-system.md) — Arquitetura completa de push + in-app + e-mail
- [notification-copy-library.md](./references/notification-copy-library.md) — 100+ copys em PT-BR prontos
- [xp-curve.md](./references/xp-curve.md) — Fórmulas de curva de XP, balanceamento de economia
- [firestore-rules-template.md](./references/firestore-rules-template.md) — Regras anti-cheat
- [analytics-events.md](./references/analytics-events.md) — Catálogo de eventos GA4/Amplitude
- [ethical-guardrails.md](./references/ethical-guardrails.md) — Checklist de ética e LGPD
- [mcp-recommendations.md](./references/mcp-recommendations.md) — Detalhes de configuração de cada MCP útil
## Princípio Raiz
> Boa gameficação é aquela que faz a pessoa ir dormir mais feliz consigo mesma do que acordou.
Esse é o filtro final de toda decisão. Se uma mecânica gera engajamento mas deixa o usuário ansioso, culpado ou exausto, ela está errada — independentemente do KPI subir. Empresas que entendem isso escalam de verdade, no longo prazo.