openprompt-lang 1.2.6 → 1.3.0

package/docs/OPL-ERRORES.md

@@ -0,0 +1,504 @@
+# 📋 Auditoría OPL — AppMobilSaaSEcommerce
+
+> **Generado:** 2026-05-23
+> **Propósito:** Documentar todos los errores, problemas de anotaciones, y deuda técnica encontrada en el proyecto para resolverlos sistemáticamente.
+
+---
+
+## 📊 Resumen del proyecto
+
+| Aspecto | Valor |
+|---------|-------|
+| Stack | React 18 + Vite 6 + TypeScript 5.9 + Tailwind 3 |
+| Mobile | Ionic 8 + Capacitor 7 (Android/iOS) |
+| Backend | Supabase (Auth, DB, Realtime, Storage, Edge Functions) |
+| Archivos totales | ~90+ archivos fuente |
+| Componentes UI | 31 componentes de página + 49 shadcn/ui |
+| Hooks | 10 hooks personalizados |
+| Archivos con anotaciones OPL | **3 de 50+** (✅ `useOfflineQueue`, `useCapacitorLifecycle`, `DeliveryZones`, `pushNotifications`) |
+| Archivos sin anotaciones OPL | **~46 archivos** |
+| Tests unitarios | **0** |
+
+---
+
+## 🚨 CATEGORÍA 1: Anotaciones OPL faltantes
+
+### 1.1 — `src/App.tsx` — Sin anotaciones OPL
+**Archivo:** `src/App.tsx` (266 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(page)
+// @contract(in: void -> out: JSX.Element)
+// @limit(lines: 300, deps: 10)
+// @deps(@external: [react, sonner, lucide-react], @internal: [
+//   ./components/Login, ./components/Dashboard, ./components/Catalog,
+//   ./components/Reports, ./components/BottomNav, ./components/Settings,
+//   ./components/Notifications, ./components/QueueModal,
+//   ./components/OfferExecutionModal, ./components/CalendarModal,
+//   ./components/OfflineRestrictionModal, ./components/PinPadModal,
+//   ./hooks/useAuth, ./hooks/useAppData, ./hooks/useOfflineQueue,
+//   ./hooks/useCapacitorLifecycle, ./hooks/useRealtimeSync,
+//   ./hooks/useProducts, ./hooks/useOrders, ./hooks/useOffers,
+//   ./hooks/useMetrics, ./services/pushNotifications
+// ])
+```
+
+### 1.2 — `src/main.tsx` — Sin anotaciones OPL
+**Archivo:** `src/main.tsx` (11 líneas)
+
+```typescript
+// @use(kind, deps)
+// @kind(entry)
+// @deps(@external: [react-dom, @ionic/react], @internal: [./App])
+```
+
+### 1.3 — `src/hooks/useAuth.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useAuth.ts` (98 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: void -> out: UseAuthReturn)
+// @limit(lines: 100)
+// @deps(@external: [react, sonner, @supabase/supabase-js], @internal: [../lib/supabase])
+```
+
+### 1.4 — `src/hooks/useAppData.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useAppData.ts` (199 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: void -> out: UseAppDataReturn)
+// @limit(lines: 200, params: 0)
+// @deps(@external: [react, sonner, @supabase/supabase-js], @internal: [
+//   ../lib/supabase, ../lib/cache, ../utils/mappers, ../types
+// ])
+```
+
+### 1.5 — `src/hooks/useOrders.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useOrders.ts` (97 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: UseOrdersOptions -> out: UseOrdersReturn)
+// @limit(lines: 100)
+// @deps(@external: [react, sonner, @supabase/supabase-js], @internal: [../lib/supabase, ../types])
+```
+
+### 1.6 — `src/hooks/useProducts.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useProducts.ts` (256 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: UseProductsOptions -> out: UseProductsReturn)
+// @limit(lines: 260, params: 1)
+// @deps(@external: [react, sonner, @supabase/supabase-js], @internal: [
+//   ../lib/supabase, ../lib/cache, ../types/product, ../types
+// ])
+```
+
+### 1.7 — `src/hooks/useOffers.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useOffers.ts` (60 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: UseOffersOptions -> out: UseOffersReturn)
+// @limit(lines: 60)
+// @deps(@external: [react, sonner, @supabase/supabase-js], @internal: [../lib/supabase, ../lib/cache, ../types])
+```
+
+### 1.8 — `src/hooks/useRealtimeSync.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useRealtimeSync.ts` (102 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: UseRealtimeSyncOptions -> out: void)
+// @limit(lines: 105)
+// @deps(@external: [react, sonner, @supabase/supabase-js], @internal: [
+//   ../lib/supabase, ../types, ../types/product, ../utils/mappers
+// ])
+```
+
+### 1.9 — `src/hooks/useMetrics.ts` — Sin anotaciones OPL
+**Archivo:** `src/hooks/useMetrics.ts` (154 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @contract(in: orders: Order[], products: Product[], reviews: any[], userMetrics -> out: { metrics, isCrunching })
+// @limit(lines: 155)
+// @deps(@external: [react], @internal: [../types, ../types/product])
+```
+
+### 1.10 — `src/hooks/useDeliveryZones.ts` — TIENE anotaciones (bien)
+✅ Archivo ya tiene `// @use(kind, contract, limit, deps)` correctamente.
+
+### 1.11 — `src/lib/supabase.ts` — Sin anotaciones OPL
+**Archivo:** `src/lib/supabase.ts` (27 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(lib)
+// @contract(in: void -> out: SupabaseClient)
+// @limit(lines: 30)
+// @deps(@external: [@supabase/supabase-js])
+```
+
+### 1.12 — `src/lib/cache.ts` — Sin anotaciones OPL
+**Archivo:** `src/lib/cache.ts` (59 líneas)
+
+```typescript
+// @use(kind, contract, limit)
+// @kind(service)
+// @contract(in: setCache(key, data, ttl) -> void | getCache(key) -> T | null)
+// @limit(lines: 60)
+```
+
+### 1.13 — `src/lib/queue.ts` — Sin anotaciones OPL
+**Archivo:** `src/lib/queue.ts` (65 líneas)
+
+```typescript
+// @use(kind, contract, limit)
+// @kind(service)
+// @contract(in: QueueItem -> out: void)
+// @limit(lines: 65)
+```
+
+### 1.14 — `src/lib/storage.ts` — Sin anotaciones OPL
+**Archivo:** `src/lib/storage.ts` (91 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(service)
+// @contract(in: files: File[], productId: string -> out: string[])
+// @limit(lines: 95)
+// @deps(@external: [@supabase/supabase-js], @internal: [./supabase])
+```
+
+### 1.15 — `src/lib/sanitizer.ts` — Sin anotaciones OPL
+**Archivo:** `src/lib/sanitizer.ts` (27 líneas)
+
+```typescript
+// @use(kind, contract, limit)
+// @kind(util)
+// @contract(in: text: string | undefined | null -> out: string)
+// @limit(lines: 30)
+// @forbidden(any)
+```
+
+### 1.16 — `src/lib/supabaseLogger.ts` — Sin anotaciones OPL
+**Archivo:** `src/lib/supabaseLogger.ts` (172 líneas)
+
+```typescript
+// @use(kind, contract, limit, deps)
+// @kind(service)
+// @contract(in: supabaseUrl: string -> out: class SupabaseLogger)
+// @limit(lines: 175)
+// @deps(@external: [crypto])
+```
+
+---
+
+## 🔴 CATEGORÍA 2: Componentes sin anotaciones OPL
+
+### 2.1 — Componentes de página (todos sin anotaciones)
+
+| Archivo | Líneas | Anotaciones |
+|---------|--------|-------------|
+| `src/components/Dashboard.tsx` | 148 | ❌ Faltan |
+| `src/components/Catalog.tsx` | 379 | ❌ Faltan |
+| `src/components/Login.tsx` | 294 | ❌ Faltan |
+| `src/components/Reports.tsx` | 388 | ❌ Faltan |
+| `src/components/Settings.tsx` | 402 | ❌ Faltan |
+| `src/components/BottomNav.tsx` | 57 | ❌ Faltan |
+| `src/components/Notifications.tsx` | 167 | ❌ Faltan |
+| `src/components/OrderDetail.tsx` | 391 | ❌ Faltan |
+| `src/components/OrderCard.tsx` | 92 | ❌ Faltan |
+| `src/components/ProductCard.tsx` | 183 | ❌ Faltan |
+| `src/components/ProductForm.tsx` | 468 | ❌ Faltan (**MUY GRANDE**, debe dividirse) |
+| `src/components/UserManagement.tsx` | 238 | ❌ Faltan |
+| `src/components/ReviewModeration.tsx` | 171 | ❌ Faltan |
+| `src/components/InboxTab.tsx` | 31 | ❌ Faltan |
+| `src/components/ActiveOrdersTab.tsx` | 31 | ❌ Faltan |
+| `src/components/HistoryTab.tsx` | — | ❌ Faltan |
+| `src/components/DeliveryZones.tsx` | 272 | ✅ **TIENE** anotaciones |
+
+### 2.2 — Modales (todos sin anotaciones)
+
+| Archivo | Líneas | Anotaciones |
+|---------|--------|-------------|
+| `src/components/PinPadModal.tsx` | 176 | ❌ Faltan |
+| `src/components/OfferBuilderModal.tsx` | 202 | ❌ Faltan |
+| `src/components/OfferExecutionModal.tsx` | — | ❌ Faltan |
+| `src/components/QueueModal.tsx` | — | ❌ Faltan |
+| `src/components/StockModal.tsx` | — | ❌ Faltan |
+| `src/components/RejectModal.tsx` | — | ❌ Faltan |
+| `src/components/DelayedConfirmModal.tsx` | — | ❌ Faltan |
+| `src/components/CalendarModal.tsx` | — | ❌ Faltan |
+| `src/components/ChangePasswordModal.tsx` | — | ❌ Faltan |
+| `src/components/CategoryPickerModal.tsx` | — | ❌ Faltan |
+| `src/components/AboutModal.tsx` | — | ❌ Faltan |
+| `src/components/OfflineRestrictionModal.tsx` | — | ❌ Faltan |
+| `src/components/ConnectionDebugModal.tsx` | — | ❌ Faltan (código muerto) |
+| `src/components/DebugPanel.tsx` | — | ❌ Faltan (código muerto) |
+
+### 2.3 — Servicios
+
+| Archivo | Líneas | Anotaciones |
+|---------|--------|-------------|
+| `src/services/pushNotifications.ts` | 93 | ✅ **TIENE** anotaciones |
+
+### 2.4 — Utils
+
+| Archivo | Líneas | Anotaciones |
+|---------|--------|-------------|
+| `src/utils/mappers.ts` | 46 | ❌ Faltan |
+| `src/utils/imageUtils.ts` | 73 | ❌ Faltan |
+
+### 2.5 — Web/Theme
+
+| Archivo | Líneas | Anotaciones |
+|---------|--------|-------------|
+| `src/web/ThemeContext.tsx` | 62 | ❌ Faltan |
+| `src/web/themes.ts` | — | ❌ Faltan |
+
+---
+
+## 🟡 CATEGORÍA 3: Errores de diseño y código detectados
+
+### 3.1 — 🔴 Overfetching masivo de Supabase
+**Archivo:** `src/hooks/useAppData.ts` (líneas 101-124)
+```typescript
+// ❌ Se traen TODAS las columnas de 5 tablas
+const ordersPromise = supabase.from('orders').select('*, order_items(*)').range(0, 99);
+const productsPromise = supabase.from('products').select('*');
+```
+**Impacto:** $40-80/mes extra en ancho de banda de Supabase.
+
+### 3.2 — 🔴 3 canales Realtime en vez de 1
+**Archivo:** `src/hooks/useRealtimeSync.ts` (líneas 28-93)
+```typescript
+// ❌ 3 suscripciones separadas
+supabase.channel('public:orders')...
+supabase.channel('public:offer_reminders')...
+supabase.channel('public:products')...
+```
+**Impacto:** $20-50/mes extra. Debe ser un solo canal.
+
+### 3.3 — 🔴 Efecto colateral dentro de setState
+**Archivo:** `src/hooks/useProducts.ts` (líneas 140-191)
+```typescript
+setProducts(prevProducts => {
+    // ❌ Llamada a Supabase DENTRO del updater de setState
+    supabase.from('products').update(updates).eq('id', productId).then(...)
+    return prevProducts.map(...)
+});
+```
+**Impacto:** Anti-pattern grave. Causa doble ejecución en StrictMode.
+
+### 3.4 — 🔴 Sin RLS en tablas principales
+**Archivo:** `supabase/migrations/`
+- ✅ `admin_push_tokens` → RLS implementado
+- ✅ `event_logs` → RLS implementado
+- ❌ `orders` → SIN RLS
+- ❌ `products` → SIN RLS
+- ❌ `order_items` → SIN RLS
+- ❌ `product_reviews` → SIN RLS
+- ❌ `offer_reminders` → SIN RLS
+- ❌ `delivery_zones` → SIN RLS
+- ❌ `user_profiles` → SIN RLS
+
+**Impacto:** Cualquiera con la anon key puede leer/modificar/borrar datos.
+
+### 3.5 — 🔴 `.env` comiteado en Git
+**Archivo:** `.env`
+```env
+VITE_SUPABASE_URL=https://cszlktmntlyqeslilpnu.supabase.co
+VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
+```
+**Impacto:** Credenciales expuestas permanentemente en el historial de Git.
+
+### 3.6 — 🔴 PIN secreto hardcodeado
+**Archivo:** `src/components/Login.tsx` (línea 9)
+```typescript
+const CREATION_SECRET_PIN = '738250';
+```
+**Impacto:** Cualquiera que lea el código sabe el PIN para crear cuentas admin.
+
+### 3.7 — 🟡 N+1 queries en bulk offer
+**Archivo:** `src/hooks/useProducts.ts` (líneas 221-228)
+```typescript
+// ❌ N updates individuales en vez de 1 batch
+const uparts = updates.map(u => supabase.from('products').update({...}).eq('id', u.id));
+await Promise.all(uparts);
+```
+
+### 3.8 — 🟡 `useMemo` usado como `useEffect`
+**Archivo:** `src/App.tsx` (líneas 102-106)
+```typescript
+// ❌ useMemo es para valores computados, no efectos
+useMemo(() => { registerPushNotifications(user.id) }, [user?.id]);
+```
+
+### 3.9 — 🟡 JSON.stringify como dependencias de useEffect
+**Archivo:** `src/hooks/useMetrics.ts` (líneas 144-151)
+```typescript
+// ❌ Serialización completa en cada render
+useEffect(() => { ... }, [JSON.stringify(orders.map(...))]);
+```
+
+### 3.10 — 🟡 Hook monstruo useAppData
+**Archivo:** `src/hooks/useAppData.ts` (199 líneas)
+**Problema:** Maneja 11 estados + 7 setters de 5 dominios diferentes (products, orders, reviews, reminders, metrics, dbStatus, loading).
+
+### 3.11 — 🟡 ProductForm de 468 líneas
+**Archivo:** `src/components/ProductForm.tsx` (468 líneas)
+**Problema:** Supera el límite recomendado de 200-250 líneas. Debe dividirse en subcomponentes.
+
+### 3.12 — 🟡 Caché inconsistente
+**Archivo:** `src/hooks/useAppData.ts` (líneas 81-136)
+**Problema:** `setCache` guarda datos crudos de Supabase, pero `getCache` consume datos mapeados. Hay doble transformación.
+
+### 3.13 — 🟡 fetchRole llamado dos veces en useAuth
+**Archivo:** `src/hooks/useAuth.ts` (líneas 46-69)
+**Problema:** `getSession()` dispara fetchRole y `onAuthStateChange` también lo dispara para el evento INITIAL_SESSION.
+
+### 3.14 — 🟡 handleDeleteUser solo elimina perfil, no auth user
+**Archivo:** `src/components/UserManagement.tsx` (línea 103)
+```typescript
+await supabase.from('user_profiles').delete().eq('id', id);
+// ❌ auth.users sigue existiendo
+```
+
+### 3.15 — 🟡 Código muerto: ConnectionDebugModal, DebugPanel
+**Archivos:** `src/components/ConnectionDebugModal.tsx`, `src/components/DebugPanel.tsx`
+**Problema:** Componentes que existen pero no se importan ni usan en App.tsx.
+
+### 3.16 — 🟡 49 componentes shadcn/ui instalados, muchos sin usar
+**Archivo:** `src/components/ui/` (49 archivos)
+**Problema:** Se instaló shadcn/ui completo pero muchos componentes (carousel, chart, command, context-menu, hover-card, input-otp, menubar, navigation-menu, pagination, resizable, scroll-area, sidebar, slider, toggle-group, tooltip, etc.) no se usan.
+
+### 3.17 — 🟡 16 CSS modulares + Tailwind duplicados
+**Archivo:** `src/styles/*.css` (16 archivos)
+**Problema:** Se mezcla Tailwind (`@apply`) con CSS clásico, duplicando estilos y aumentando el bundle.
+
+### 3.18 — 🟡 sanitizer.ts rompe caracteres UTF-8
+**Archivo:** `src/lib/sanitizer.ts` (líneas 16-20)
+```typescript
+.replace(/'/g, '’')  // ❌ Rompe "Don's Special" → "Don’s Special"
+.replace(/"/g, '”')  // ❌ Rompe comillas válidas
+```
+
+### 3.19 — 🟡 Edge Functions no integradas con frontend
+**Archivos:** `supabase/functions/` (4 funciones)
+**Problema:** `apply-queue` duplica lógica del frontend, `sync-snapshot` nunca se llama, `new-order` solo logea.
+
+### 3.20 — 🟡 16 parámetros en useCapacitorLifecycle
+**Archivo:** `src/hooks/useCapacitorLifecycle.ts` (líneas 12-31)
+**Problema:** Demasiadas propiedades en el options object (code smell).
+
+### 3.21 — 🟡 Alias @/ configurado pero no usado
+**Archivos:** `vite.config.ts:51`, `tsconfig.json:23-24`
+```json
+"paths": { "@/*": ["./src/*"] }
+```
+**Problema:** Ningún archivo importa con `@/`, todos usan rutas relativas como `../`.
+
+### 3.22 — 🟡 edge functions `_shared/` con secretos hardcodeados potenciales
+**Archivo:** `supabase/functions/notify-admin/index.ts`
+**Problema:** Usa `Deno.env.get()` para credenciales de Firebase, pero no hay validación de que existan.
+
+### 3.23 — 🟢 Duplicación de scrollbar-hide y hide-scrollbar
+**Archivo:** `src/index.css` (líneas 90-104)
+**Problema:** Dos utility classes con el mismo propósito.
+
+### 3.24 — 🟢 Variables CSS --brand-* duplican propósito de Tailwind
+**Archivo:** `src/index.css` (líneas 37-41)
+**Problema:** Las variables CSS solo se usan en los CSS modulares, no en Tailwind.
+
+### 3.25 — 🟢 Sin tests unitarios
+**Problema:** No hay ningún archivo de test (`*.test.ts`, `*.spec.ts`). No se puede verificar regresión.
+
+---
+
+## 💰 Impacto económico estimado en Supabase
+
+| Problema | Costo/mes | Solución |
+|----------|-----------|----------|
+| Overfetching (SELECT *) | $40-80 | Columnas específicas |
+| 3 canales Realtime | $20-50 | 1 canal |
+| N+1 queries bulk offers | $5-15 | Batch `.in()` |
+| Sin RLS (riesgo de abuso) | $100+ | RLS policies |
+| Sin paginación real | $10-30 | Cursor-based |
+| **Total evitable** | **~$75-175/mes** | |
+
+---
+
+## 📋 Checklist de resolución
+
+### 🔴 Prioridad 1 — Seguridad (HACER AHORA)
+
+- [ ] **P1.1** Agregar `@use()`, `@kind`, `@contract`, `@deps` a TODOS los archivos
+- [ ] **P1.2** Implementar RLS en todas las tablas (orders, products, order_items, product_reviews, offer_reminders, delivery_zones, user_profiles)
+- [ ] **P1.3** Agregar `.env` a `.gitignore` y rotar la anon key
+- [ ] **P1.4** Mover PIN secreto a variable de entorno
+- [ ] **P1.5** Fix: handleToggleSale — sacar efecto colateral de setState
+
+### 🔴 Prioridad 2 — Performance (HACER PRONTO)
+
+- [ ] **P2.1** Optimizar fetchData con columnas específicas + paginación cursor-based
+- [ ] **P2.2** Reducir de 3 a 1 canal Realtime con filtros por tabla
+- [ ] **P2.3** Cambiar N+1 queries a batch update con `.in()`
+- [ ] **P2.4** Reemplazar `useMemo` por `useEffect` en push notifications
+
+### 🟡 Prioridad 3 — Refactor (PLAZO MEDIO)
+
+- [ ] **P3.1** Separar `useAppData` en hooks por dominio
+- [ ] **P3.2** Dividir ProductForm en subcomponentes (< 250 líneas c/u)
+- [ ] **P3.3** Unificar CSS: eliminar 16 CSS modulares, usar solo Tailwind
+- [ ] **P3.4** Limpiar shadcn/ui no utilizados
+- [ ] **P3.5** Eliminar código duplicado (compressImage, scrollbar classes)
+- [ ] **P3.6** Eliminar código muerto (ConnectionDebugModal, DebugPanel)
+- [ ] **P3.7** Usar alias @/ en imports
+- [ ] **P3.8** Revisar/fix sanitizer.ts (no romper UTF-8)
+- [ ] **P3.9** Integrar Edge Functions reales con frontend
+- [ ] **P3.10** Agregar test unitarios (mínimo 1 por hook)
+
+### 🟢 Prioridad 4 — Deuda técnica menor
+
+- [ ] **P4.1** Crear @learn-error por cada bug fijo
+- [ ] **P4.2** Configurar `prompt-lang.json` con strict mode
+- [ ] **P4.3** Establecer dominio en `prompt-lang.json`
+- [ ] **P4.4** Ejecutar `npx openprompt-lang qa-gen` para generar tests
+
+---
+
+## 📌 Archivos con anotaciones OPL ya existentes (para referencia)
+
+✅ Estos archivos ya tienen anotaciones y sirven como modelo:
+
+1. `src/hooks/useOfflineQueue.ts`
+2. `src/hooks/useCapacitorLifecycle.ts`
+3. `src/hooks/useDeliveryZones.ts`
+4. `src/services/pushNotifications.ts`
+5. `src/components/DeliveryZones.tsx`
+
+---
+
+## 🏁 Notas finales
+
+Este documento debe actualizarse a medida que se resuelvan los problemas.
+Cada vez que se corrija un error, agregar:
+```typescript
+// @learn-error id=XXX input='...' expected=200 actual=500 fix='...'
+```
+
+---
+
+*Documento generado durante sesión de auditoría OPL — 2026-05-23*

package/docs/OPL_ACADEMIC_ISSUES.md

@@ -0,0 +1,158 @@
+# 🎓 OPL Academic — Bitácora de Problemas
+
+> Documento para registrar problemas, fricciones y errores detectados en el sistema de enseñanza (Teaching System) de openPrompt-Lang.
+> Cada entrada documenta: síntoma, causa raíz, impacto, solución propuesta y estado.
+
+---
+
+## 📋 Índice de Problemas
+
+| # | Fecha | Título | Severidad | Estado |
+|---|-------|--------|-----------|--------|
+| 1 | 2026-05-24 | Onboarding IA en proyecto existente | 🔴 Alta | Abierto |
+| 2 | 2026-05-24 | `opl rebuild` no detecta OPL automáticamente | 🟡 Media | Abierto |
+| 3 | 2026-05-24 | Falta documento post-init para IA | 🔴 Alta | Abierto |
+
+---
+
+## 🐛 Problemas Reportados
+
+### P-001: Onboarding IA en proyecto existente
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | 2026-05-24 |
+| **Reportado por** | usuario |
+| **Severidad** | 🔴 Alta |
+| **Módulo** | Academic — Init / Onboarding |
+| **Estado** | 🔴 Abierto |
+
+**Síntoma:**
+Al iniciar una sesión con IA en un proyecto existente que ya tiene elementos de OPL, la IA no sabe qué hacer. No hay un punto de entrada claro que le diga "esto ya tiene OPL, aquí está el estado actual, continúa desde aquí".
+
+**Causa raíz:**
+No existe un documento de onboarding generado automáticamente que la IA pueda leer al inicio de cada sesión para restaurar contexto.
+
+**Impacto:**
+- La IA pierde ~15 minutos regenerando contexto cada sesión
+- Toma decisiones inconsistentes porque no conoce el estado real del proyecto
+- El usuario tiene que re-explicar manualmente lo que ya se hizo
+
+**Solución propuesta:**
+- Crear `docs/ONBOARDING_WORKFLOW.md` — documento canónico que la IA lee al iniciar
+- Integrar `opl init` para que genere este documento automáticamente
+- Dos versiones: `INICIAR_NUEVO.md` (proyecto nuevo) e `INICIAR_EXISTENTE.md` (proyecto en curso)
+
+**Referencias:**
+- `erroresDeFlujo.md` (línea 2)
+- Sprint embeddings → TICKET-011 (propuesto)
+
+---
+
+### P-002: `opl rebuild` no detecta OPL automáticamente
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | 2026-05-24 |
+| **Reportado por** | usuario |
+| **Severidad** | 🟡 Media |
+| **Módulo** | CLI — rebuild |
+| **Estado** | 🟡 Abierto |
+
+**Síntoma:**
+`opl rebuild` falla o funciona incorrectamente cuando los elementos de OPL no están presentes o no son detectables automáticamente.
+
+**Causa raíz:**
+El comando `rebuild` asume cierta estructura pre-existente en lugar de ser autosuficiente.
+
+**Solución propuesta:**
+Hacer que `rebuild` funciones en dos modos:
+1. **Con detección**: Si encuentra elementos OPL, los respeta y reconstruye
+2. **Sin detección**: Si no encuentra nada, crea la estructura desde cero con defaults inteligentes
+
+**Referencias:**
+- `erroresDeFlujo.md` (línea 4)
+
+---
+
+### P-003: Falta documento post-init para IA
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | 2026-05-24 |
+| **Reportado por** | usuario |
+| **Severidad** | 🔴 Alta |
+| **Módulo** | CLI — init |
+| **Estado** | 🔴 Abierto |
+
+**Síntoma:**
+Después de ejecutar `opl init`, no se genera ningún documento que la IA pueda usar para entender el contexto del proyecto. La IA llega "en frío" a cada sesión.
+
+**Causa raíz:**
+`opl init` configura el proyecto (crea prompt-lang.json, AGENTS.md, etc.) pero no genera un punto de entrada específico para la IA que le diga "esto es lo que hay, esto es lo que falta, continúa".
+
+**Solución propuesta:**
+Que `opl init` genere automáticamente:
+- `INICIAR_NUEVO.md` si es proyecto nuevo
+- `INICIAR_EXISTENTE.md` si es proyecto existente con OPL
+
+Estos documentos deben incluir:
+- Stack detectado
+- Estado de la configuración OPL
+- Próximos pasos recomendados
+- Enlace a `AGENTS.md` y `docs/AI_CONTEXT.md`
+
+**Referencias:**
+- `erroresDeFlujo.md` (línea 6)
+- `docs/ONBOARDING_WORKFLOW.md`
+
+---
+
+## 📊 Estadísticas
+
+| Métrica | Valor |
+|---------|-------|
+| Total problemas | 3 |
+| Severidad Alta | 2 |
+| Severidad Media | 1 |
+| Severidad Baja | 0 |
+| Abiertos | 3 |
+| En Progreso | 0 |
+| Resueltos | 0 |
+
+---
+
+## 📝 Cómo Reportar un Problema Nuevo
+
+Usa esta plantilla al añadir una nueva entrada:
+
+```markdown
+### P-XXX: Título descriptivo
+
+| Campo | Valor |
+|-------|-------|
+| **Fecha** | YYYY-MM-DD |
+| **Reportado por** | — |
+| **Severidad** | 🔴 Alta / 🟡 Media / 🟢 Baja |
+| **Módulo** | — |
+| **Estado** | 🔴 Abierto |
+
+**Síntoma:**
+_¿Qué ocurre exactamente?_
+
+**Causa raíz:**
+_¿Por qué ocurre?_
+
+**Impacto:**
+_¿A quién afecta y cómo?_
+
+**Solución propuesta:**
+_¿Cómo se arreglaría?_
+
+**Referencias:**
+- _enlaces a código, docs, commits_
+```
+
+---
+
+*Última actualización: 2026-05-24*