taskbot/docs/whatsapp-style-guide.md

Guía de Estilo de Mensajes para WhatsApp (Help v2)

Objetivo: mensajes claros, consistentes y resistentes a cambios menores de copy.

Principios

• Responder por DM: incluso si el comando viene de un grupo, las respuestas al usuario llegan por privado. Nota: en modo gating estricto (GROUP_GATING_MODE='enforce') el bot puede no responder en grupos no permitidos.
• Estructura visual reconocible:
  • Secciones en negrita y MAYÚSCULAS: *COMANDOS BÁSICOS*.
  • Comandos e IDs en monoespaciado (backticks).
  • Listas con “- ” por línea.
  • Notas en cursiva.
• Brevedad y accionabilidad: priorizar ejemplos cortos y CTAs (“Prueba /t ayuda”, “Envía /t web”).
• Estabilidad para tests: evitar asserts por igualdad exacta; preferir substrings semánticos.

Componentes de formato

• Encabezados de sección:
  • Patrón: *${TÍTULO EN MAYÚSCULAS}*
  • Ej.: *COMANDOS BÁSICOS*
• Comandos:
  • Siempre en backticks: `/t ver mis`
• IDs:
  • Mostrar con 4 dígitos entre backticks: `0026` (usar codeId()).
• Fechas:
  • Mostrar como DD/MM, precedidas de icono si aplica (ej.: ⚠️ si vencida). Usar formatDDMM().
• Notas:
  • En cursiva: _Este grupo no está activo._
• Bullets:
  • “- ” al inicio de cada línea. Evitar listas demasiado largas (>10).

Emojis recurrentes

• ⚠️ Advertencia (vencida, no encontrado, truncado).
• ✅ Confirmación genérica.
• 📅 Fecha (según ICONS.date).
• 👤 / 👥 Responsables (uno o varios).
• ➕ Crear, ✔️ Completar, 🧲/✋ Tomar/Soltar (según ICONS disponibles).
• Evitar exceso: 1–2 por línea como máximo.

Patrones comunes

• Confirmación de creación:
  • Línea 1: icono + ID + descripción
  • Línea 2: fecha (si existe)
  • Línea 3: responsable(s) o “sin responsable”
• Listados:
  • Título (nombre de grupo o Tus tareas)
  • Bullets de items con: ID, descripción, fecha (con ⚠️ si vencida), responsable
  • Sufijo “... y N más” si aplica
• Ayuda rápida:
  • Secciones: “COMANDOS BÁSICOS”, “LISTADOS”, “ACCESO WEB”
  • Bullets con ejemplos: `/t n ...`, `/t ver mis|grupo|todos|sin`, `/t x 26`, `/t tomar 12`, `/t configurar ...`, `/t web`

Localización

• Todo copy en español. Evitar fugas de claves internas en inglés (ej. “weekly”).
• En recordatorios, exponer etiquetas en español:
  • daily → “diario”
  • weekdays → “laborables (lunes a viernes)”
  • weekly → “semanal (lunes)”
  • off → “apagado”
• Si por compatibilidad se aceptan términos en inglés como input, la respuesta debe mantener español.

Buenas prácticas

• Evitar párrafos largos; preferir 1–3 líneas por bloque.
• Los mensajes de 'Uso:' llevan el prefijo ℹ️.
• Incluir uso cuando falten argumentos:
  • Ej.: ℹ️ Uso: \/t tomar 26` o múltiples: `/t tomar 12 19 50` o `/t tomar 12,19,50` (máx. 10)`
• Mensajes de error claros y accionables: “No puedes tomar esta tarea… Pide acceso a un admin si crees que es un error.”
• En listados, omitir líneas en blanco finales.

Para tests

• Preferir asserts de “contiene” con fragmentos estables (IDs en backticks, comandos en backticks, nombres de secciones).
• Si hace falta, crear helper stripFormatting que quite *, _ y ` para comparar texto plano.

Ejemplos

Ayuda rápida

*COMANDOS BÁSICOS*
- `/t n Descripción 2025-11-05 @Ana`
- `/t ver` (en grupo) · `/t ver mis` (DM) · `/t ver todos`
- `/t x 26` · `/t tomar 12`
- `/t configurar diario|l-v|semanal|off [HH:MM]`
- `/t web`
_El bot responde por DM, incluso si escribes desde un grupo._

Confirmación de completar (ya estaba)

ℹ️ `0026` ya estaba completada — Preparar informe — 📅 05/11

Listado de “sin responsable”

Nombre del Grupo — Sin responsable
- `0142` Revisión de PR — 📅 12/03
- `0185` Montar demo — ⚠️ 📅 09/03
... y 3 más