Agendas y disponibilidad

---
name: agendas-y-disponibilidad
description: reservar un horario real sin dobles citas ni errores de zona horaria.
---

# Agendas y disponibilidad

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando una
persona publique horarios, reserve citas o sincronice calendarios.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Clientes reservan servicios, consultas, clases, demos o recursos.
- La disponibilidad depende de horario laboral, descansos, buffers o días bloqueados.
- Dos calendarios deben evitar choques.
- Hay recordatorios, reprogramación, cancelación o citas recurrentes.

Si solo eliges una fecha sin disponibilidad limitada, usa un campo de fecha. No modeles
slots, holds y calendarios para una preferencia que nadie puede agotar.

## Cómo armarla

Usa **Postgres** para reglas y reservas, **Luxon** o `date-fns-tz` para zonas IANA y
**Google Calendar API** solo después de que la agenda interna funcione sola.

1. Guarda instantes confirmados en UTC y la zona IANA original, como
   `America/Mexico_City`. Expresa horarios semanales en la zona del negocio, no como UTC.
2. Modela disponibilidad como reglas más excepciones: horario semanal, feriados, bloqueos,
   buffers, anticipación mínima, horizonte máximo, duración, capacidad y recursos.
3. Calcula slots en el servidor para un rango acotado. Convierte a la zona de quien mira
   solo al presentar y muestra ambas zonas cuando organizador e invitado difieren.
4. Al seleccionar, crea un hold corto con expiración. Confirma dentro de una transacción
   con una restricción que impida traslape; volver a consultar antes de insertar no basta.
5. Usa una llave idempotente al confirmar. Un doble clic o reintento debe devolver la
   misma reserva, no ocupar dos espacios.
6. Trata calendario externo como integración, no como base principal: guarda id externo,
   `etag` o token de sincronización, estado y última sincronización. Reconcilia cambios.
7. Genera invitación ICS y recordatorios desde una cola. Cancelar o reprogramar crea un
   historial y actualiza todos los canales, no sobrescribe el pasado.
8. Ofrece enlaces firmados de duración limitada para cancelar o mover una cita sin crear
   cuenta, si el riesgo del servicio lo permite.

## En qué te vas a trabar

- **El horario de verano rompe offsets fijos.** Prueba cambios DST aunque tu ciudad no
  cambie reloj; el cliente, profesional o calendario conectado puede vivir en otra zona.
- **La concurrencia crea dobles reservas.** Dos confirmaciones simultáneas deben competir
  en la base de datos, no en memoria ni en botones deshabilitados.
- **Google y Microsoft envían cambios repetidos y parciales.** Usa tokens incrementales,
  webhooks idempotentes y una reconciliación periódica.
- **Recordatorios cuestan por canal.** Calcula correo, WhatsApp o SMS con la tarifa vigente
  y permite que el negocio elija cuáles justifican el margen.

## Qué NO hacer

- No guardes solo `-06:00`; el offset no contiene reglas futuras de zona horaria.
- No crees todos los slots del año como filas por adelantado.
- No prometas sincronización bidireccional si solo importas eventos una vez.
- No borres citas canceladas ni liberes un hold sin verificar quién lo posee.

## Checklist

- [ ] Reglas, excepciones, buffers, capacidad y recursos producen los slots esperados.
- [ ] UTC y zona IANA sobreviven cambios DST y reservas entre países.
- [ ] Dos confirmaciones simultáneas no crean traslape.
- [ ] Holds vencen solos y confirmar dos veces devuelve la misma reserva.
- [ ] Cancelación y reprogramación conservan historial y actualizan invitaciones.
- [ ] La sincronización externa tolera duplicados, expiración de token y cambios remotos.
- [ ] Recordatorios respetan zona, horario silencioso, consentimiento y presupuesto.