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 paquetes (cada paquete = 2 DMs consecutivos con breve retraso), separados al menos 14 días y solo si no hubo interacción desde el primer paquete.
• Alias de comandos más cortos y claros para fomentar uso por DM.

---

Fase 0 — Auditoría y decisiones de compatibilidad (Completada)

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) (Completada)

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 en paquetes (2 DMs, migración mínima para interacción) (Completada)

Objetivos

• Enviar un paquete de 2 DMs (Mensaje 1 + Mensaje 2) por usuario cuando se crea una tarea en un grupo.
  • Mensaje 1: CTA “/t tomar {CÓDIGO}” + “/t info”.
  • Mensaje 2: mini‑chuleta (“/t mias”, “/t todas”, “/t configurar …”, “/t web”), 5–10 s después del Mensaje 1.
• Repetir el mismo paquete una única vez más si pasan ≥ 14 días sin interacción del usuario (si hubo interacción, no se envía el segundo paquete).
• 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 con metadata { kind='onboarding', variant, part, bundle_id } y soporte de retraso para el segundo DM del paquete; getOnboardingStats)
• src/services/command.ts (desencadenar el paquete tras crear tarea en grupo, respetando gating y caps; actualizar users.last_command_at al recibir cualquier comando)
• src/services/allowed-groups.ts (usado para gating en modo enforce)
• src/db/migrations/* (añadir columna users.last_command_at) y wiring en src/db/migrator.ts
• 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', part: 1|2, bundle_id, group_id, task_id, display_code }.
  • getOnboardingStats(recipient): { total, lastSentAt, lastVariant?: 'initial'|'reminder' } consultando response_queue por metadata.kind='onboarding'.
  • Soportar programar el segundo DM del paquete con un retraso aleatorio de 5000–10000ms.
• 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ígitos puros con longitud < 14,
    • 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:
    • Si no hay paquetes previos → encolar paquete 'initial' con 2 DMs (part=1 ahora; part=2 con retraso).
    • Si hay paquete 'initial' y han pasado ≥14 días SIN interacción (users.last_command_at ≤ primer paquete) → encolar paquete 'reminder' (2 DMs).
    • En cualquier otro caso → no enviar.
• Envío del primer DM del paquete inmediato (next_attempt_at = now) y el segundo con pequeño retraso. Ventanas horarias opcionales (ver Fase 4).

Copys de onboarding (exactos)

• Mensaje 1 (en ambos disparos):
  • “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.”
• Mensaje 2 (mini‑chuleta; se envía tras 5–10 s, en ambos disparos):
  • “Guía rápida (este es un mensaje único): · Tus tareas: /t mias · Todas: /t todas · Recordatorios: /t configurar diario | l‑v | semanal | off · Web: /t web”

Impacto en tests

• Tests unitarios para:
  • Construcción de destinatarios (exclusiones, cap).
  • Paquetes: por disparo se encolan 2 DMs/usuario (part=1 y part=2 con retraso).
  • Recordatorio a los ≥14 días solo si no hubo interacción desde el primer paquete; si la hubo, skip.
  • Gating enforce (grupo no allowed → no enviar).
  • Metadata de enqueue (kind='onboarding', variant initial|reminder, part 1|2, bundle_id).

Notas sobre migraciones

• Migración mínima recomendada: añadir users.last_command_at para registrar la última interacción del usuario y así decidir si enviar el segundo paquete tras ≥14 días. Actualizar este campo al procesar cualquier comando entrante.
• Si no se implementa, el recordatorio se puede degradar a “si han pasado ≥14 días desde el primer paquete”, sin comprobar interacción (menos preciso).

---

Fase 3 — Ajustes de ayuda (Help v2) y refuerzos en DMs operativos (No se implementará)

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 (No se implementará)

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, part=1|2, group_id)
• onboarding_bundle_sent_total (labels: variant=initial|reminder, group_id) — opcional
• 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', 'had_interaction'
• 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_BUNDLE_DELAY_MS=4000
• 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 (No se implementará)

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:
  • Por evento de creación en grupo se encolan 2 DMs/usuario (part=1 inmediato y part=2 con retraso).
  • Tras ≥14 días sin interacción desde el primer paquete, se encola un segundo paquete idéntico; si hubo interacción, no se encola.
  • Gating enforce: grupos no permitidos → no enviar.
  • Metadata de response_queue correcta (kind, variant, part, bundle_id).
• Help v2 actualizado (snapshots).
• CTAs añadidos al final de DMs operativos.

---

Fase 6 — Despliegue y control (No se implementará)

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) (No se implementará)

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 | off · 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.

---