---
type: SPEC
asset_id: SPEC-REB-RClub-KatIA-OnboardingImpl-Gustavo-v01
version: v01.5
status: Vigente — listo para implementar (piloto IronMan)
owner: Anahí Martínez
sherpa_owner: Anix
ratificador: Victor Heredia
destinatario: Gustavo (Frontend · EmpowerLabs)
fecha_creacion: 2026-06-24
fecha_ultima_actualizacion: 2026-07-09
intellbank: IB-REB-Rebelocity
subbank: RebelocityClub
proposito: >
  Brief técnico para la implementación del onboarding KatIA en Rebelocity Club.
  Piloto: solo segmento IronMan/70.3. Sistema de puntos y ReClub Card suspendidos
  para el piloto (reactivar en fase 2). Badge Fundador como única recompensa visible.
  Cubre: formulario /profile, estado ARRANCA via balance endpoint, badge Fundador,
  Curiosity Pistas y catálogo dinámico.
referencias_canonicas:
  - TP-REB-RClub-KatIA-OnboardingPrompt-v02 (prompt · v02.3 vigente)
  - REB-RClub-ARRANCA-ExperienciaOnboarding-v01 (diseño de ARRANCA)
  - REB-RClub-CuriosityPistas-Diseno-v01 (diseño de las 5 pistas)
  - KB-REB-RClub-KatIA-CanalContexto-v01 (KB actual)
  - PLAN-REB-RClub-OnboardingImpl-Gustavo-v01 (plan de implementación de Gustavo · v01.2)
tags: [spec, implementacion, katia, arranca, curiosity-pistas, gustavo, frontend, badge, ironman, piloto]
---

# SPEC · KatIA Onboarding — Brief de Implementación
## Rebelocity Club · Para: Gustavo · v01.5 · Julio 2026

**Owner:** Anahí Martínez | **Sherpa:** Anix | **Ratificador:** Victor Heredia
**Destinatario:** Gustavo (Frontend · EmpowerLabs)

> **Alcance del piloto:**
> - Segmento: **solo IronMan / 70.3**. L'Étape suspendido hasta 2027.
> - Sistema de puntos y ReClub Card: **suspendidos**. Las action_keys están sembradas en BD para cuando se reactive, pero KatIA no los llama en el piloto y el usuario nunca ve puntos ni menciones a la tarjeta.
> - Única recompensa visible al usuario: **badge Fundador** al completar CP7.

---

## Contexto en 3 líneas

KatIA es el chat de bienvenida en la home de Rebelocity Club. Cuando un usuario nuevo entra, KatIA lo guía por **ARRANCA** — 7 checkpoints que recorren toda la plataforma — y después le da **Curiosity Pistas** para mantener el engagement. El prompt completo está en `TP-REB-RClub-KatIA-OnboardingPrompt-v02`. Este documento cubre **lo que la plataforma necesita hacer para que ese prompt funcione**.

---

## Vista general del flujo (piloto)

```
Usuario nuevo se registra
        │
        ▼
KatIA lanza ARRANCA (7 checkpoints · solo IronMan)
        │
        ├── CP1 · /profile completado         [automático · Jesús]
        ├── CP2 · Noticia leída + frase        [KatIA-triggered · sin award en piloto]
        ├── CP3 · Playbook abierto + concepto  [KatIA-triggered · sin award en piloto]
        ├── CP4 · Sherpa consultado + respuesta [KatIA-triggered · sin award en piloto]
        ├── CP5 · Directorio visitado + nombre  [KatIA-triggered · sin award en piloto]
        ├── CP6 · Post en foro + confirmación  [KatIA-triggered · sin award en piloto]
        └── CP7 · Evento encontrado + nombre   [KatIA-triggered]
                                                → badge Fundador (única recompensa visible)
        │
        ▼
Post-ARRANCA: Curiosity Pistas (una por sesión, hasta 5)
        └── Cada pista validada               [KatIA-triggered · sin award en piloto]
```

> **Sistema de puntos — estado en piloto:** las action_keys (`cp1_completado` ... `pista_5`) están sembradas en BD por Jesús con cooldown `once` y `requires_card = TRUE`. No se llaman en el piloto. Cuando se reactive la ReClub Card, solo hay que habilitar las llamadas al endpoint — sin trabajo de infraestructura adicional.

---

## 1. Lo que la plataforma necesita hacer

### 1.1 · CP1 — el único trigger activo en el piloto

El único trigger de backend que sigue activo en el piloto es el que detecta que el usuario guardó el formulario Sherpa IA, para que KatIA pueda saber que CP1 está completo.

Jesús ya implementó esto: `cp1_completado` se dispara automáticamente desde backend cuando el frontend llama `POST /ai-sherpa/user/data/save` con `model === 'profile'`. Gustavo no necesita hacer nada extra — solo asegurarse de que el guardado del formulario use ese endpoint.

### 1.2 · Estado de ARRANCA — derivado del balance endpoint

KatIA no necesita campos propios — deriva todo el estado consultando:

```
GET /api-nodejs/api/points/award/balance?userId=[id]&actions=true

→ { userId, balance, actions: [
      { actionKey, actionName, totalPoints, count, awardedAt }, ...
    ] }
```

Con la lista de `actions`, KatIA calcula:
- Qué checkpoints completó (`cp1_completado` ... `cp7_completado` en la lista)
- Cuál checkpoint sigue (el primero de la secuencia 1-7 que no esté)
- Si ya completó ARRANCA (`cp7_completado` presente)
- Qué Curiosity Pistas ya dio (`pista_1` ... `pista_5` en la lista)

> **Nota piloto:** en el piloto solo `cp1_completado` se registra automáticamente. Los demás checkpoints (CP2–CP7) y las pistas se validan conversacionalmente por KatIA pero **no se llama al award endpoint**. KatIA maneja el estado de la sesión en memoria durante la conversación. El balance endpoint sigue siendo útil para CP1 y para saber si el usuario ya tiene el badge Fundador.

### 1.3 · Campo `arranca_version` en /profile

```
arranca_version: "ironman" | null
```

En el piloto siempre es `"ironman"`. Se deja el campo preparado para cuando se sume L'Étape.

### 1.4 · Badge Fundador

- **Trigger:** cuando KatIA valida el CP7 en el chat
- **Implementación piloto:** etiqueta de texto en el perfil: `🧡 Fundador · Rebelocity Club`
- Aparece debajo del nombre en perfil y en el Directorio (si tiene perfil público)
- Permanente — no se puede quitar
- KatIA ya incluye la confirmación en el script del CP7

> **Pregunta para Jesús:** ¿el badge se puede asignar llamando al award de `cp7_completado`? Si sí, KatIA puede dispararlo cuando valida el checkpoint en el chat — sin necesidad de panel manual. Si no, Anahí lo asigna manualmente desde el panel.

---

## 2. Formulario Sherpa IA en /profile

### 2.1 · Las 4 preguntas

1. ¿Cuál es tu historia como atleta?
2. ¿Qué meta estás persiguiendo ahora?
3. ¿Qué obstáculo estás enfrentando hoy?
4. ¿Cómo quieres que te acompañe tu Sherpa?

### 2.2 · Implementación

- **Pregunta 1** → reutilizar el campo `bio` existente. Mapear bio → "historia del atleta". Sin campo nuevo.
- **Preguntas 2, 3 y 4** → campos nuevos a construir.
- **Campo `arranca_version`** → también va en /profile.
- **Puntos CP1** → Jesús los dispara automáticamente al detectar guardado de `model === 'profile'` en `POST /ai-sherpa/user/data/save`. Gustavo solo construye el formulario y asegura que el guardado use ese endpoint.

---

## 3. Curiosity Pistas

### 3.1 · Tracking

El balance endpoint registra las pistas que KatIA marcó como completadas. En el piloto, KatIA valida la respuesta en el chat pero no llama al award endpoint — lleva el estado de qué pistas ya dio en memoria durante la conversación.

Cuando se reactive el sistema de puntos: KatIA llamará `POST /api-nodejs/api/points/award` con `actionKey: "pista_1"` ... `"pista_5"` para cada pista validada.

### 3.2 · Tabla de action_keys de pistas (para cuando se reactivene puntos)

| Action Key | Dato correcto |
|---|---|
| `pista_1` | 30% (artículo de rendimiento mental en Noticias) |
| `pista_2` | 7:34:37 (récord de Sam Laidlow en Kona) |
| `pista_3` | Copa del Mundo Triatlón · Asunción · agosto 2026 |
| `pista_4` | Half Ironman Under 5 · Taylor Reed (Librería) |
| `pista_5` | Lionel Sanders · descanso = estrategia (Noticias) |

---

## 4. Catálogo dinámico de playbooks

**Solución piloto:** catálogo en archivo separado `CAT-REB-RClub-Playbooks-Activos.md` con Título + Autor + Descripción. Anahí lo actualiza manualmente cuando se publica nuevo contenido. KatIA infiere disciplina/nivel/público del texto de la descripción.

**Deseable:** script que regenere el catálogo automáticamente cuando se publica un playbook.

---

## 5. Resumen — lo que Gustavo necesita implementar

### 5.1 · Crítico para el lanzamiento del piloto

| # | Qué | Complejidad | Nota |
|---|---|---|---|
| 1 | Formulario Sherpa IA en /profile: reutilizar `bio` como Pregunta 1, construir Preguntas 2-4 + campo `arranca_version` | Alta | CP1 award lo dispara Jesús automáticamente — sin lógica de puntos en frontend |
| 2 | Dar a KatIA acceso a `GET /api-nodejs/api/points/award/balance?userId=[id]&actions=true` al inicio de conversación | Media | Para derivar estado de ARRANCA y pistas |
| 3 | Badge Fundador — etiqueta en perfil al completar CP7 | Baja | Trigger: KatIA valida CP7 en chat. Confirmar con Jesús si el award de `cp7_completado` aplica el badge |

### 5.2 · Deseable para el lanzamiento

| # | Qué | Complejidad |
|---|---|---|
| 4 | Leaderboard de ARRANCA (quiénes tienen el badge Fundador) | Media |
| 5 | Script de catálogo dinámico de playbooks | Media |

### 5.3 · Suspendido — reactivar en fase 2 (ReClub Card)

| Qué | Cuándo reactivar |
|---|---|
| Llamadas a `POST /api-nodejs/api/points/award` para CP2–CP7 y pistas | Cuando se lance la ReClub Card |
| Trigger automático de +5 pts al completar registro | Ídem |
| Tabla de puntos visible al usuario | Ídem |

---

## 6. Preguntas del SPEC §7 — respondidas

| Pregunta | Respuesta |
|---|---|
| ¿El panel admin permite asignar puntos manualmente? | ✅ Sí — confirmado por Jesús. Útil para el badge Fundador en el piloto si no se puede disparar automáticamente. |
| ¿KatIA recibe arranca_state y pistas_state al inicio? | ✅ Resuelto vía balance endpoint — Gustavo conecta ese acceso al inicio de cada conversación. |
| ¿Existe webhook cuando se publica contenido nuevo? | ⚠️ No confirmado — catálogo es manual en el piloto. |
| ¿El sistema de puntos de la ReClub Card existe o se construye? | ✅ Existe (Jesús lo tiene). Suspendido para el piloto — se activa en fase 2. |

---

## CHANGELOG

| Versión | Fecha | Cambio |
|---|---|---|
| v01 | 2026-06-24 | Creación. Brief técnico completo. |
| v01.1 | 2026-06-24 | CP3 y CP6 movidos a KatIA-triggered. |
| v01.2 | 2026-06-24 | §6.1 corregida (playbook y foro removidos de automáticos; endpoint cubre 11 acciones). |
| v01.3 | 2026-06-24 | Arquitectura simplificada: arranca_state/pistas_state eliminados, balance endpoint. Catálogo Opción A. Bio reutilizada para Pregunta 1. |
| v01.4 | 2026-07-02 | Integración del PLAN de Gustavo: rutas reales del API de Jesús, CP1 backend-automático, 11 action_keys sembradas. |
| v01.5 | 2026-07-09 | Piloto solo IronMan/70.3: L'Étape eliminado (evento San Bernardino movido a 2027). Sistema de puntos y ReClub Card suspendidos para el piloto — action_keys sembradas y listas para fase 2, pero no se llaman. Badge Fundador como única recompensa visible. Tabla §5 simplificada: solo 3 ítems críticos + 2 deseables + tabla de suspendidos. Nota al badge Fundador: confirmar con Jesús si el award de cp7_completado lo aplica automáticamente. |

---

*Rebelocity Club · SPEC Implementación KatIA Onboarding · v01.5 · Julio 2026*
*Owner: Anahí Martínez | Sherpa: Anix | Ratificador: Victor Heredia*
*Para: Gustavo — Frontend · EmpowerLabs*