taskbot/docs/plan-onboarding-comandos.md

# Plan por fases: Onboarding por DM y simplificación de comandos

Este documento define un plan incremental para:
- Introducir onboarding por DM no intrusivo (máx. 2 DMs por usuario, espaciados 14 días).
- Simplificar los comandos de visualización.
- Ajustar el material de ayuda.
- Añadir métricas y banderas de configuración.
- Mantener "cero mensajes en grupos" (solo reacciones).

Se prioriza minimizar migraciones y cambios de superficie, aprovechando infraestructura existente (ResponseQueue, GroupSync, Identity/Contacts, Help v2).

Estado actual relevante (resumen)
- El bot ya responde por DM a acciones de tareas y evita escribir en grupos (salvo reacciones).
- Listados de tareas: “ver grupo/mis/todas/sin”.
- Help v2 en src/services/messages/help.ts (copys).
- Envío de mensajes mediante ResponseQueue con metadata JSON (ya se usa para reacciones).
- GroupSync mantiene una cache y utilidades de membresía y snapshot frescas.
- No hay aún estado explícito de onboarding por usuario.

Principios
- Nunca escribimos mensajes en grupos (solo reacciones).
- Onboarding solo se dispara cuando se crea una tarea en un grupo (evento con “excusa” clara).
- Onboarding por usuario: máx. 2 DMs, separados al menos 14 días; si no interactúa, no insistimos más.
- Alias de comandos más cortos y claros para fomentar uso por DM.

---

## Fase 0 — Auditoría y decisiones de compatibilidad

Objetivos
- Acordar defaults y compatibilidad de comandos.
- Confirmar feature flags y límites.
- Asegurar que no afectaremos flujos sensibles.

Archivos a consultar
- src/services/command.ts
- src/services/messages/help.ts
- src/utils/whatsapp.ts
- src/services/allowed-groups.ts
- tests relacionados con comandos de listado (no incluidos aquí)

Overview de cambios (sin código)
- Definir que en DM “/t ver” (sin argumentos) se comporte como “todas”.
- Mantener compatibilidad con “/t ayuda”, pero comunicar “/t info” como alias preferido.
- Aceptar “/t mias” y “/t todas” como atajos (alias de “ver mis” y “ver todas”).
- En contexto de grupo, cualquier intento de “ver …” no debe listar en el grupo; se responderá por DM (mensaje breve de transición).
- Flags/env de onboarding (ver Fase 4).

Criterios de aceptación
- Decisión documentada: “/t ver” en DM => “todas”.
- Alias permitidos y comunicados en help.
- Confirmación de “cero mensajes en grupo”.

---

## Fase 1 — Alias y routing de comandos (sin onboarding aún)

Objetivos
- Añadir y mapear alias “info” → “ayuda”; “mias” → “ver mis”; “todas” → “ver todas”.
- Cambiar default de “/t ver” (en DM) a “todas”.
- En grupo, redirigir listados a DM con mensaje corto de transición (sin listar en el grupo).

Archivos a modificar
- src/services/command.ts
- src/services/messages/help.ts (copys actualizados con alias)
- src/utils/icons.ts y src/utils/formatting.ts (solo si se requiere algún símbolo/estilo nuevo)

Overview de cambios
- Extender ACTION_ALIASES y/o routing para nuevas acciones y scopes.
- Detectar contexto de grupo y bloquear listados en el grupo (enviar por DM un mensaje de transición: “No respondo en grupos. Tus tareas: /t mias · Todas: /t todas · Info: /t info · Web: /t web”).
- Help v2: mostrar “/t mias”, “/t todas”, “/t info”; retirar “ver grupo” de la guía básica y sugerir web para ver todo el grupo.

Impacto en tests
- Actualizar tests que esperen “/t ver” => “mis” en DM.
- Añadir tests de alias (“mias”, “todas”, “info”).
- Tests de transición desde grupo (no hay listados en el grupo; respuesta por DM).

---

## Fase 2 — Infra de Onboarding por DM (sin migraciones)

Objetivos
- Implementar un onboarding DM que se dispare al crear una tarea en un grupo, con 2 variantes:
  - Mensaje 1 (initial): CTA “/t tomar {CÓDIGO}” + “/t info”.
  - Mensaje 2 (reminder): mini‑chuleta (“/t mias”, “/t todas”, “/t configurar …”, “/t web”).
- Cumplir reglas: máx. 2 DMs por usuario, separados ≥ 14 días; cap por evento; sin mensajes en grupos.

Archivos a modificar
- src/services/group-sync.ts (añadir listActiveMemberIds(groupId): string[])
- src/services/response-queue.ts (añadir helpers para onboarding: enqueueOnboarding y getOnboardingStats; reutilizar metadata JSON con kind='onboarding')
- src/services/command.ts (desencadenar onboarding tras crear tarea en grupo, respetando gating y caps)
- src/services/allowed-groups.ts (usado para gating en modo enforce)
- src/services/identity.ts y src/services/contacts.ts (solo consumo; no se cambian)

Overview de cambios
- GroupSyncService: nuevo helper para obtener IDs de miembros activos del grupo (solo dígitos, grupos activos, no comunidad/archivados).
- ResponseQueue:
  - enqueueOnboarding(recipient, message, metadata) con metadata canónica: { kind: 'onboarding', variant: 'initial'|'reminder', group_id, task_id, display_code }.
  - getOnboardingStats(recipient): { total, lastSentAt } consultando response_queue por metadata.kind='onboarding'.
- CommandService (en /t nueva):
  - Tras crear la tarea en grupo, construir candidatos:
    - miembros activos del grupo (GroupSync.listActiveMemberIds),
    - excluir creador, asignados y el número del bot,
    - filtrar por /^\d+$/,
    - si GROUP_GATING_MODE=enforce y el grupo no está allowed → no enviar.
  - Cap por evento (ONBOARDING_EVENT_CAP, p. ej. 30).
  - Para cada destinatario:
    - stats.total=0 → enviar Mensaje 1.
    - stats.total=1 y lastSentAt <= now-14 días → enviar Mensaje 2.
    - En cualquier otro caso → no enviar.
- Envío inmediato (next_attempt_at = now). Ventanas horarias opcionales (ver Fase 4).

Copys de onboarding (exactos)
- Mensaje 1:
  - “Hola, soy el bot de tareas. En ‘{Grupo}’ acaban de crear una tarea: #{CÓDIGO} {descripción corta}
     Encárgate: envíame /t tomar {CÓDIGO} por privado· Más info: /t info (también por privado)
     Nota: Solo respondo por privado. (Este mensaje solo lo envío una vez)”
- Mensaje 2 (mini‑chuleta, solo si no interactuó aún):
  - “Guía rápida (este es un mensaje único):
     · Tus tareas: /t mias · Todas: /t todas
     · Recordatorios: /t configurar diario | l‑v | semanal
     · Web: /t web”

Impacto en tests
- Tests unitarios para:
  - Construcción de destinatarios (exclusiones, cap).
  - Idempotencia por usuario (0 → initial; 1 y >14d → reminder; resto skip).
  - Gating enforce (grupo no allowed → no enviar).
  - Metadata de enqueue (kind='onboarding', variant correcto).

Notas sobre migraciones
- No se requiere migración: se usa response_queue como fuente de verdad para conteo/fecha de onboarding por usuario (consultando metadata.kind='onboarding').

---

## Fase 3 — Ajustes de ayuda (Help v2) y refuerzos en DMs operativos

Objetivos
- Actualizar help rápido/completo con alias y nuevas recomendaciones.
- Añadir CTAs discretos al final de DMs operativos existentes (ack al crear y DM al asignado).

Archivos a modificar
- src/services/messages/help.ts
- src/services/command.ts (añadir línea discreta al final de acks y DMs al asignado)

Overview de cambios
- Help rápido:
  - “Ver mis: /t mias (por privado)”
  - “Ver todas: /t todas (por privado)”
  - “Más info: /t info”
  - Retirar “ver grupo” de la guía básica; sugerir web (“/t web”).
- Help completo: reflejar “mias/todas/info” y la política de “no responder en grupos”.
- CTAs discretos al final de DMs operativos:
  - “Tus tareas: /t mias · Todas: /t todas · Info: /t info · Web: /t web”

Impacto en tests
- Actualizar snapshots/expectativas del help y de los DMs.

---

## Fase 4 — Métricas y flags de configuración

Objetivos
- Medir adopción y salud del onboarding y de alias.
- Controlar comportamiento con variables de entorno.

Archivos a modificar
- src/services/command.ts (instrumentación Metrics.inc/set donde corresponda)
- src/services/response-queue.ts (contadores al encolar onboarding)
- src/services/group-sync.ts (counters si se desea, p. ej. “onboarding_skipped_not_allowed”)
- src/services/metrics.ts (no requiere cambios de API)

Métricas propuestas
- onboarding_dm_sent_total (labels: variant=initial|reminder, group_id)
- onboarding_dm_skipped_total (labels: reason, group_id)
  - reasons: 'cooldown_active', 'capped_event', 'not_allowed', 'disabled', 'no_members', 'no_group', 'not_group_context', 'no_display_code'
- onboarding_recipients_capped_total (labels: group_id)
- commands_alias_used_total (labels: action=info|mias|todas)
- commands_blocked_total (ya existe para gating; mantener)

Flags/env sugeridas
- ONBOARDING_DM_ENABLED=true
- ONBOARDING_DM_COOLDOWN_DAYS=14
- ONBOARDING_EVENT_CAP=30
- ONBOARDING_ENABLE_IN_TEST=false (o true si se van a probar envíos en tests)
- GROUP_GATING_MODE=enforce|off (ya existente)
- Opcional (si se diferencia horario amable): ONBOARDING_SILENCE_HOURS=22-08 (futuro)

Overview de cambios
- Usar Metrics.inc/set en los puntos de decisión.
- Leer flags con defaults robustos y sin romper tests.

---

## Fase 5 — Tests y validación end-to-end

Objetivos
- Cubrir alias nuevos, cambios de routing, y lógica de onboarding.
- Garantizar “cero mensajes en grupo”.

Áreas de test
- Alias:
  - “/t info” → ayuda
  - “/t mias” → listado de asignadas
  - “/t todas” → listado combinado (DM)
  - “/t ver” (DM) → “todas”
- Contexto grupo:
  - Invocar listados desde un grupo responde por DM con transición (no lista en el grupo).
- Onboarding:
  - Evento de creación en grupo dispara destinatarios esperados (excluye creador/asignados/bot; cap).
  - 0 → initial, 1 y >14 días → reminder, resto → skip.
  - Gating enforce: grupos no permitidos → no enviar.
  - Metadata de response_queue correcta (kind, variant).
- Help v2 actualizado (snapshots).
- CTAs añadidos al final de DMs operativos.

---

## Fase 6 — Despliegue y control

Objetivos
- Desplegar con seguridad y capacidad de rollback.
- Observar métricas clave.

Checklist de despliegue
- Activar ONBOARDING_DM_ENABLED en staging, validar envíos y métricas.
- Validar alias y help actualizados.
- Monitorizar:
  - onboarding_dm_sent_total vs skipped.
  - Uso de “/t mias”, “/t todas”, “/t info”.
  - web_tokens_issued_total (por “/t web”).
- Habilitar en producción. Ajustar ONBOARDING_EVENT_CAP si hay grupos muy grandes.

---

## Fase 7 — Consideraciones futuras (no bloqueantes)

Ideas a evaluar después
- “Bienvenida al primer DM inbound” (mensaje corto de bienvenida una única vez cuando el usuario inicia chat).
- Ventanas horarias: programar next_attempt_at si se detecta horario nocturno (requiere mínima lógica extra).
- Tabla explícita de onboarding (si se quiere persistir fuera de response_queue), p. ej. user_onboarding con timestamps y contadores.
- Resumen semanal opt‑in (ya soportado con “/t configurar …”): medir retención y satisfacción.

---

## Resumen de archivos a cambiar (referencia)

- src/services/command.ts
  - Alias y routing: “info”, “mias”, “todas”; “/t ver” en DM => “todas”.
  - Mensaje de transición al detectar listados desde grupo (solo DM).
  - Disparo de onboarding tras crear tarea en grupo (con caps y cooldown).
  - CTAs discretos al final de acks y DMs al asignado.
  - Instrumentación de métricas.

- src/services/messages/help.ts
  - Actualizar copys a “/t mias”, “/t todas”, “/t info”.
  - Retirar “ver grupo” del básico y empujar web para ver todo el grupo.

- src/services/group-sync.ts
  - Añadir listActiveMemberIds(groupId): string[].

- src/services/response-queue.ts
  - Añadir enqueueOnboarding() y getOnboardingStats().
  - Incrementar métricas al encolar.

- src/services/allowed-groups.ts
  - Solo consumo para gating (no cambios de API).

- src/utils/whatsapp.ts, src/utils/formatting.ts, src/utils/icons.ts
  - Sin cambios estructurales; mantener estilos y símbolos.

- src/services/metrics.ts
  - Reutilización. No requiere cambios, solo llamadas desde los puntos anteriores.

---

## Copys finales (para implementación)

1) Onboarding — Mensaje 1 (initial)
- “Hola, soy el bot de tareas. En ‘{Grupo}’ acaban de crear una tarea: #{CÓDIGO} {descripción corta}
  Encárgate: /t tomar {CÓDIGO} · Más info: /t info
  Nota: nunca respondo en grupos; solo por privado.”

2) Onboarding — Mensaje 2 (reminder, único)
- “Guía rápida (este es un mensaje único):
  · Tus tareas: /t mias · Todas: /t todas
  · Recordatorios: /t configurar diario | l‑v | semanal
  · Web: /t web”

3) Transición cuando se intenta listar desde grupo (responder por DM)
- “No respondo en grupos. Tus tareas: /t mias · Todas: /t todas · Info: /t info · Web: /t web”

4) Línea discreta al final de DMs operativos (ack creación y DM a asignados)
- “Tus tareas: /t mias · Todas: /t todas · Info: /t info · Web: /t web”

---

## Riesgos y mitigaciones

- Saturación en grupos grandes → Cap por evento (ONBOARDING_EVENT_CAP, p. ej. 30) + cooldown 14 días por usuario.
- IDs no resueltos → Filtrar a /^\d+$/ y excluir alias no mapeados.
- Confusión por comandos antiguos → Alias “mias/todas/info” visibles en help; mensajes de transición desde grupo.
- Métricas y observabilidad → Añadir contadores con labels para entender adopción y fricción.

---