From 3dea7a3334aadc6e43d17a1ffb3949e197884dc7 Mon Sep 17 00:00:00 2001
From: Marco Gallegos <marco.gallegos@outlook.com>
Date: Mon, 15 Dec 2025 17:43:49 -0600
Subject: [PATCH] Create tasks.md

---
 tasks.md | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 275 insertions(+)
 create mode 100644 tasks.md

diff --git a/tasks.md b/tasks.md
new file mode 100644
index 0000000..3ab08d6
--- /dev/null
+++ b/tasks.md
@@ -0,0 +1,275 @@
+# TASKS.md
+
+Este documento define un **plan de ejecución secuencial**, con **menos fases pero más coherentes**, pensadas para ejecutarse **una tras otra sin ambigüedad**, ideal para un agente de IA desarrollador o un equipo técnico.
+
+Principio rector:
+
+> *Cada fase deja el sistema en un estado funcional, testeable y estable.*
+
+---
+
+## Fase 1 – Base del Sistema (Infraestructura + Entrada)
+
+**Objetivo:** recibir mensajes de Telegram y dejarlos listos para procesar.
+
+### 1.1 Bootstrap del Proyecto
+
+* Crear estructura de carpetas según README.
+* Configurar entorno virtual.
+* Instalar dependencias.
+* FastAPI levantando correctamente.
+
+Resultado: API viva sin lógica de negocio.
+
+---
+
+### 1.2 Variables de Entorno
+
+Definir `.env` con:
+
+* TELEGRAM_BOT_TOKEN
+* OPENAI_API_KEY
+* GOOGLE_APPLICATION_CREDENTIALS
+* SPREADSHEET_ID
+* ENV (dev / prod)
+
+El sistema **no debe arrancar** si falta alguna.
+
+---
+
+### 1.3 Webhook de Telegram
+
+* Endpoint `/telegram/webhook`.
+* Validar origen del mensaje.
+* Log completo del payload en modo dev.
+
+Resultado: mensajes entran y se registran.
+
+---
+
+### 1.4 Input Handler
+
+Implementar `input_handler.py`:
+
+* Texto.
+* Voz (solo stub inicialmente).
+* Imagen (solo stub inicialmente).
+* PDF (solo stub).
+
+Todo debe normalizarse a texto crudo.
+
+Resultado: cualquier input termina como texto limpio.
+
+---
+
+## Fase 2 – Modelo de Datos y Estados
+
+**Objetivo:** tener claridad absoluta sobre qué es un gasto y en qué estado vive.
+
+### 2.1 Modelos Pydantic
+
+Crear modelos:
+
+* RawInput
+* ExtractedExpense
+* ProvisionalExpense
+* FinalExpense
+
+Cada modelo debe validar su propio dominio.
+
+---
+
+### 2.2 Estados del Gasto
+
+Definir estados explícitos:
+
+* RECEIVED
+* ANALYZED
+* AWAITING_CONFIRMATION
+* CONFIRMED
+* CORRECTED
+* STORED
+
+No se permiten saltos implícitos.
+
+Resultado: máquina de estados clara.
+
+---
+
+## Fase 3 – Configuración como Lógica
+
+**Objetivo:** mover la inteligencia determinística fuera del código.
+
+### 3.1 Loader de Configuración
+
+Implementar `config_loader.py`:
+
+* Cargar CSV y JSON.
+* Normalizar texto.
+* Cachear en memoria.
+* Validar esquema mínimo.
+
+Fallar rápido si algo está mal configurado.
+
+---
+
+### 3.2 Matching de Proveedores
+
+* Matching por nombre y aliases.
+* Coincidencia parcial, case-insensitive.
+* Retornar score de match.
+
+Regla dura: si hay match fuerte, **no usar IA**.
+
+---
+
+### 3.3 Matching de Keywords
+
+* Buscar keywords en descripciones.
+* Permitir múltiples matches.
+* Resolver conflictos por prioridad.
+
+Resultado: clasificación determinística siempre que sea posible.
+
+---
+
+## Fase 4 – The Analyst (Procesamiento Inteligente)
+
+**Objetivo:** convertir texto crudo en un gasto provisional estructurado.
+
+### 4.1 Extracción Multimodal (Completa)
+
+* Voz → transcripción IA.
+* Imagen → OCR IA.
+* PDF → extracción semiestructurada.
+
+Unificar todo en texto limpio.
+
+---
+
+### 4.2 Clasificación en Cascada
+
+Pipeline obligatorio:
+
+1. Proveedores
+2. Keywords
+3. Inferencia IA (último recurso)
+
+Registrar siempre **por qué camino** se tomó la decisión.
+
+---
+
+### 4.3 Validación Fiscal Básica
+
+* Detectar CFDI.
+* Extraer RFC receptor.
+* Comparar con `user_config.json`.
+* Anotar observaciones, no bloquear.
+
+---
+
+### 4.4 Score de Confianza
+
+* Regla directa → alta.
+* Keywords → media.
+* IA pura → baja.
+
+Persistir el score.
+
+Resultado: gasto provisional listo para revisión humana.
+
+---
+
+## Fase 5 – Interacción y Auditoría
+
+**Objetivo:** asegurar control humano y trazabilidad.
+
+### 5.1 Mensaje de Confirmación
+
+Enviar al usuario:
+
+* Proveedor
+* Monto
+* Categoría
+* Tipo (personal / negocio)
+* Observaciones
+* Score de confianza
+
+Formato corto, claro y editable.
+
+---
+
+### 5.2 Parsing de Correcciones
+
+Aceptar lenguaje natural:
+
+* "el monto es 180"
+* "es personal"
+* "la fecha fue ayer"
+
+No asumir intención: solo cambios explícitos.
+
+---
+
+### 5.3 The Auditor
+
+* Comparar estado previo vs nuevo.
+* Aplicar solo cambios solicitados.
+* Registrar auditoría:
+
+```
+AUDITORÍA: campo X cambió de A a B (timestamp)
+```
+
+Nada se sobreescribe silenciosamente.
+
+---
+
+## Fase 6 – Persistencia y Cierre
+
+**Objetivo:** guardar datos finales de forma segura y limpia.
+
+### 6.1 Google Sheets
+
+* Hojas separadas: personal / negocio.
+* Append-only.
+* Manejo de errores de red.
+
+---
+
+### 6.2 Limpieza de Estados Temporales
+
+* Eliminar colas provisionales.
+* Asegurar idempotencia.
+
+Resultado: gasto almacenado y ciclo cerrado.
+
+---
+
+## Fase 7 – Hardening y Preparación a Futuro
+
+### 7.1 Logs y Errores
+
+* Logs estructurados.
+* DEBUG solo en dev.
+* Mensajes claros al usuario.
+
+Nunca perder un gasto silenciosamente.
+
+---
+
+### 7.2 Preparación para Escalar
+
+* Aislar config por `user_id`.
+* Preparar soporte multiusuario.
+* Dejar hooks para reportes futuros.
+
+---
+
+## Regla Final para el Agente
+
+* Ejecutar fases en orden.
+* No adelantar optimizaciones.
+* Si una decisión no es obvia, documentarla.
+
+El sistema debe sentirse **confiable, explicable y humano**, antes que impresionante.