openprompt-lang 0.3.0

package/docs/referencia-metodologia/Framework de Desarrollo Asistido por IA.md

@@ -0,0 +1,1741 @@
+---
+title: Framework de Desarrollo Asistido por IA (openPrompt-Lang)
+tags: [react, ionic, capacitor, vite, tauri, tailwind, react-doctor, patrones, metodologia, prompt-lang]
+version: 1.0.0
+framework: openPrompt-Lang
+---
+
+# Framework de Desarrollo Asistido por IA (openPrompt-Lang)
+
+> Este documento es la especificación del framework **openPrompt-Lang**: un sistema de anotaciones y patrones para desarrollo asistido por IA. Combina un **lenguaje de anotaciones** (sección 0) para comunicar restricciones a la IA, con un **catálogo de patrones** para estructurar proyectos **React + TypeScript** (con o sin Ionic/Capacitor/Tauri). Cada proyecto aplica las secciones que necesita según su tipo y alcance.
+>
+> 🔗 **CLI:** `npx openPrompt-Lang` — Ver `docs/SYNTAX.md` para la especificación completa del lenguaje.
+
+---
+
+## 0. Sintaxis del Lenguaje PromptLang
+
+> Las anotaciones PromptLang permiten comunicar restricciones exactas a la IA directamente en el código, y ser validadas por el CLI `openPrompt-Lang validate`. Siguen el principio de **prompts deterministas** (sección 9) pero incrustados como comentarios.
+
+### 0.1 Sistema de Imports
+
+Todo archivo con anotaciones DEBE declarar los tags que usa:
+
+```
+// @use(kind, contract, limit, deps, platform, scope, meta)
+```
+
+| Uso | Significado |
+|---|---|
+| `@use(*)` | Todos los tags disponibles |
+| `@use(kind, contract)` | Solo los especificados |
+| Sin `@use` | Modo legacy — sin validación de anotaciones |
+
+### 0.2 Tags de Definición
+
+| Tag | Sintaxis | Descripción |
+|---|---|---|
+| `@kind` | `@kind(tipo)` | Define el tipo: `hook`, `component`, `page`, `service`, `store`, `util`, `type`, `layout`, `feature` |
+| `@pattern` | `@pattern(nombre)` | Patrón de diseño: `compound`, `composition`, `generic`, `render-prop` |
+
+### 0.3 Tags de Contrato
+
+| Tag | Sintaxis | Descripción |
+|---|---|---|
+| `@contract` | `@contract(in: tipos -> out: tipo @error: tipo)` | Interfaz de función (hooks/services) |
+| `@props` | `@props({ name: tipo, name2?: tipo })` | Props de componente (JSON-like) |
+| `@state` | `@state(loading, empty, error, success)` | Estados visuales del componente |
+
+### 0.4 Tags de Restricción
+
+| Tag | Sintaxis | Descripción |
+|---|---|---|
+| `@limit` | `@limit(lines: N, functions: N)` | Límites del archivo (defaults según @kind) |
+| `@forbidden` | `@forbidden(any, css-modules)` | Prohibiciones explícitas |
+
+### 0.5 Tags de Composición y Dependencias
+
+| Tag | Sintaxis | Descripción |
+|---|---|---|
+| `@compose` | `@compose(CompA, useHookB)` | Dependencias internas del proyecto |
+| `@deps` | `@deps(@external: [lib], @forbidden: [lib])` | Dependencias externas con sub-tags |
+
+### 0.6 Tags de Entorno
+
+| Tag | Sintaxis | Descripción |
+|---|---|---|
+| `@platform` | `@platform(web, mobile, desktop)` | Target de ejecución (con validación cruzada) |
+| `@scope` | `@scope(module: X, affects: [Y], breaking: bool)` | Alcance e impacto del módulo |
+
+### 0.7 Tags de Calidad
+
+| Tag | Sintaxis | Descripción |
+|---|---|---|
+| `@test` | `@test(@unit, @coverage: 80)` | Requisitos de testing |
+| `@meta` | `@meta(@version: "1.0", @tags: [auth])` | Metadatos del archivo |
+
+### 0.8 Ejemplo completo
+
+```typescript
+// @use(kind, contract, limit, deps, platform, scope, meta)
+// @kind(hook)
+// @limit(lines: 75, params: 2)
+// @contract(in: email, password -> out: user, token @error: AuthError)
+// @deps(@external: [supabase], @forbidden: [axios])
+// @platform(web)
+// @scope(module: auth, affects: [login, session], breaking: false)
+// @meta(@version: "1.0.0", @author: "dev", @tags: [auth, supabase])
+export function useAuth() { ... }
+```
+
+### 0.9 Reglas de Validación Cruzada
+
+```
+@kind(hook)     → @contract REQUERIDO, @props PROHIBIDO, @limit ≤80
+@kind(component) → @props RECOMENDADO, @contract PROHIBIDO, @limit ≤120
+@kind(page)      → @compose REQUERIDO, @limit ≤200
+@kind(service)   → @contract REQUERIDO, @props/state PROHIBIDO, @limit ≤150
+@kind(store)     → @deps(zustand) RECOMENDADO, @limit ≤100
+@kind(type)      → @limit/state NO APLICAN
+
+@platform(mobile) + @deps(@tauri-apps/*) → ERROR
+@platform(desktop) + @deps(@capacitor/*) → ERROR
+@scope(breaking: true) → commit debe ser breaking change (!)
+```
+
+> 📖 **Especificación completa:** `docs/SYNTAX.md` en el repositorio del framework.
+
+---
+
+### Guía de adaptación por tipo de proyecto
+
+| Tipo de proyecto | Secciones esenciales | Secciones opcionales | Secciones recomendadas |
+|---|---|---|---|
+| **Prototipo / MVP rápido** (1-2 semanas, freelance) | 2, 6, 7, 9, 10 | 3, 4, 8, 11 | 5 (solo PHASE-1) |
+| **Proyecto completo con cliente** (SaaS, app nativa) | 1, 2, 5, 6, 7, 9, 10, 12 | 3, 4, 8, 11, 13, 14 | Todo |
+| **Web puro** (Sin Tauri/Ionic, solo React + Supabase) | 2, 5, 6, 7, 8, 9, 10 | 3, 4, 11, 12 | Ignorar referencias a Capacitor/Tauri |
+| **Side project personal** | 2, 6, 7, 9 | 3, 5, 10 | 4 (solo ACTIVIDAD, sin ERRORES) |
+| **App desktop** (Tauri sin mobile) | 1, 2, 6, 7, 9, 10 | 3, 4, 5, 8, 11 | Ignorar secciones de Ionic/Capacitor |
+
+> **Regla práctica:** Si estás en fase de descubrimiento o prototipo, aplica solo secciones 2, 6, 7, 9 y 10. El resto se incorpora cuando el proyecto se formaliza con cliente o presupuesto.
+
+---
+
+## Índice
+
+0. [Sintaxis del Lenguaje PromptLang](#0-sintaxis-del-lenguaje-promptlang)
+   - [0.1 Sistema de Imports](#01-sistema-de-imports)
+   - [0.2 Tags de Definición](#02-tags-de-definición)
+   - [0.3 Tags de Contrato](#03-tags-de-contrato)
+   - [0.4 Tags de Restricción](#04-tags-de-restricción)
+   - [0.5 Tags de Composición y Dependencias](#05-tags-de-composición-y-dependencias)
+   - [0.6 Tags de Entorno](#06-tags-de-entorno)
+   - [0.7 Tags de Calidad](#07-tags-de-calidad)
+   - [0.8 Ejemplo completo](#08-ejemplo-completo)
+   - [0.9 Reglas de Validación Cruzada](#09-reglas-de-validación-cruzada)
+0a. [Guía de adaptación por tipo de proyecto](#guía-de-adaptación-por-tipo-de-proyecto)
+1. [Stack Tecnológico y Convenciones](#1-stack-tecnológico-y-convenciones)
+2. [Estructura de Carpetas Universal](#2-estructura-de-carpetas-universal)
+3. [Sistema de Commits y Bitácora](#3-sistema-de-commits-y-bitácora)
+4. [Sistema de Logs de Errores y Actividad](#4-sistema-de-logs-de-errores-y-actividad)
+   - [4.1 Automatización de Logs con Scripts](#41-automatización-de-logs-con-scripts)
+5. [Backlog por Prioridades y Fases](#5-backlog-por-prioridades-y-fases)
+6. [Reglas de Componentes y Modularización](#6-reglas-de-componentes-y-modularización)
+7. [Patrones React + Tailwind para Reutilización](#7-patrones-react--tailwind-para-reutilización)
+8. [Integración con react-doctor](#8-integración-con-react-doctor)
+9. [Estructura de Prompts — Correcto vs Incorrecto](#9-estructura-de-prompts--correcto-vs-incorrecto)
+10. [Flujo de Trabajo Diario con IA](#10-flujo-de-trabajo-diario-con-ia)
+11. [Pipeline de Validación Automática](#11-pipeline-de-validación-automática)
+12. [Phase Gates — CheckList de Salida por Fase](#12-phase-gates--checklist-de-salida-por-fase)
+13. [Retrospectiva por Iteración](#13-retrospectiva-por-iteración)
+14. [Perfiles de Desarrollador](#14-perfiles-de-desarrollador)
+15. [Biblioteca de Prompts (docs/PROMPTS/)](#15-biblioteca-de-prompts-docsprompts)
+
+---
+
+## 1. Stack Tecnológico y Convenciones
+
+### Stack base
+
+> ⚡ **Stack base obligatorio:** React + TypeScript + Vite + Tailwind. Ionic, Capacitor y Tauri son **opcionales** según el tipo de proyecto (web, mobile, desktop). Si tu proyecto es web puro, omite las secciones que referencien Capacitor/Tauri.
+
+| Tecnología | Versión Objetivo | Propósito | Obligatorio |
+|---|---|---|---|
+| React 18+ | ^18.3 | UI declarativa con hooks | ✅ |
+| TypeScript | ^5.4 | Tipado estricto | ✅ |
+| Vite | ^5.x | Build tool / dev server | ✅ |
+| Tailwind CSS | ^3.4 | Utility-first styling | ✅ |
+| react-doctor | última | Auditoría de buenas prácticas React | Recomendado |
+| Ionic Framework | ^8.x | Componentes nativos y UI mobile-first | Solo si hay mobile |
+| Capacitor | ^6.x | Acceso nativo (cámara, GPS, etc.) | Solo si hay mobile |
+| Tauri | ^2.x | Desktop nativo (Windows/Mac/Linux) | Solo si hay desktop |
+
+### Convenciones generales del stack base (siempre aplican)
+
+- **Tailwind utility-first**: Sin CSS personalizado. 100% clases de utilidad.
+- **Componentes atómicos en `components/ui/`**: Primitivas reutilizables con variantes (cva).
+- **Custom hooks para toda lógica reutilizable**: Nada de lógica en componentes.
+- **Composition > Inheritance**: Usar children, render props y compound components.
+
+### Convenciones para stacks extendidos (solo si aplican)
+
+- **Ionic solo para UI mobile-first**: Usar componentes `<IonPage>`, `<IonContent>`, `<IonButton>`, etc. en vistas mobile. En desktop se renderizan con Tauri y se prefiere UI propia con Tailwind.
+- **Capacitor como puente nativo**: Toda la lógica de plugins nativos (cámara, notificaciones, almacenamiento) va encapsulada en hooks con prefijo `useCapacitor*`.
+- **Tauri para desktop**: Los comandos de Tauri (Rust) se llaman desde servicios en `src/services/tauri/`. NO mezclar lógica de Tauri con lógica de Capacitor en el mismo archivo.
+- **Vite como orchestrator**: Vite configura tanto el build web como el de Tauri. No modificar `vite.config.ts` sin documentar el cambio.
+
+### Configuración de react-doctor
+
+> react-doctor analiza tu código React en busca de anti-patrones. Se ejecuta como parte del lint/pre-commit.
+
+```json
+{
+  "rules": {
+    "react-hooks/exhaustive-deps": "error",
+    "react/no-unused-prop-types": "warn",
+    "react/jsx-no-duplicate-props": "error",
+    "hooks-rules": "error",
+    "no-unnecessary-context": "warn",
+    "component-complexity": ["warn", { "max-lines": 120, "max-functions": 5 }],
+    "no-class-components": "error"
+  }
+}
+```
+
+**Ejecutar react-doctor antes de cada commit:**
+```bash
+npx react-doctor check ./src
+```
+
+---
+
+## 2. Estructura de Carpetas Universal
+
+```
+/
+├── src/
+│   ├── components/
+│   │   ├── ui/                  # Primitive components (Button, Input, Card, Modal)
+│   │   │   ├── Button.tsx
+│   │   │   ├── Input.tsx
+│   │   │   ├── index.ts         # Barrel export
+│   │   ├── layout/              # App shell (Navbar, Sidebar, Tabs)
+│   │   │   ├── AppShell.tsx
+│   │   │   ├── MobileNav.tsx
+│   │   │   └── DesktopSidebar.tsx
+│   │   └── shared/              # Shared domain components (UserAvatar, EmptyState)
+│   ├── features/                # Feature modules, each is a domain
+│   │   ├── auth/
+│   │   │   ├── components/      # Feature-specific components
+│   │   │   ├── hooks/           # Feature-specific hooks
+│   │   │   ├── services/        # Feature API calls
+│   │   │   ├── types/           # Feature-specific types
+│   │   │   ├── LoginPage.tsx
+│   │   │   └── RegisterPage.tsx
+│   │   ├── dashboard/
+│   │   └── products/
+│   ├── hooks/                   # Global reusable hooks
+│   │   ├── useAuth.ts
+│   │   ├── useCapacitorCamera.ts
+│   │   ├── useTauriCommand.ts
+│   │   ├── useLocalStorage.ts
+│   │   └── useDebounce.ts
+│   ├── services/                # API clients, external integrations
+│   │   ├── api/
+│   │   ├── supabase/
+│   │   └── tauri/               # Tauri IPC commands
+│   ├── store/                   # Global state (Zustand recommended)
+│   │   ├── authStore.ts
+│   │   └── uiStore.ts
+│   ├── types/                   # Global TypeScript interfaces
+│   │   └── global.d.ts
+│   ├── utils/                   # Pure utility functions
+│   │   ├── formatDate.ts
+│   │   ├── validators.ts
+│   │   └── constants.ts
+│   ├── views/                   # Page-level components (routing targets)
+│   │   ├── Home.tsx
+│   │   └── Profile.tsx
+│   ├── App.tsx
+│   ├── main.tsx
+│   └── router.tsx
+├── docs/                        # Project documentation
+│   ├── COMMITS/                 # Commit logs folder
+│   ├── LOGS/                    # Error and activity logs
+│   ├── BACKLOG/                 # Backlog and task distribution
+│   └── ARCHITECTURE.md
+├── tauri/                       # Tauri Rust source (auto-generated)
+├── capacitor/                   # Capacitor platform configs (auto-generated)
+├── android/
+├── ios/
+├── tailwind.config.ts
+├── vite.config.ts
+├── tsconfig.json
+├── package.json
+└── AGENTS.md                    # AI context file (resumen para prompts)
+```
+
+### Regla de crecimiento de carpetas
+
+- **/components/ui/**: Un archivo por componente. Máximo 150 líneas. Si supera, se divide en subcomponentes atómicos.
+- **/features/**: Una carpeta por dominio de negocio. Si un feature supera 10 archivos, se evalúa dividirlo en subfeatures.
+- **/hooks/**: Un hook por archivo. Máximo 80 líneas. Si un hook requiere más, se refactoriza en hooks más pequeños o se mueve lógica a utils.
+
+---
+
+## 3. Sistema de Commits y Bitácora
+
+> 💡 **Cuándo aplicar esta sección:** La bitácora detallada con archivos por versión es para **proyectos formales con cliente**. En prototipos y MVPs basta con commits convencionales bien escritos. Si el proyecto es personal o exploratorio, usa solo los tipos de commit y salta la carpeta `docs/COMMITS/`.
+
+### Carpeta de Commits
+
+Cada proyecto debe tener `docs/COMMITS/` con un archivo por versión o milestone:
+
+```
+docs/COMMITS/
+├── INDEX.md              # Índice cronológico de todos los commits
+├── v0.1.0-inicial.md     # Commit log de la versión inicial
+├── v0.2.0-auth.md
+└── v0.3.0-dashboard.md
+```
+
+### Formato de cada commit en el log
+
+```markdown
+## [v0.1.0] - 2026-05-13
+
+### Commit: feat(auth): implementar registro de usuario con Supabase
+**Hash:** a1b2c3d4e5f6...
+**Fecha:** 2026-05-13 14:30
+**Módulo:** auth
+**Versión:** v0.1.0
+
+#### Cambios realizados
+- Se creó `AuthService.register()` con validación de email único
+- Se agregó hook `useAuth` con estado de sesión
+- Se integró componente `LoginForm` con validación en tiempo real
+
+#### Archivos modificados
+- `src/features/auth/services/AuthService.ts` (+45 líneas)
+- `src/features/auth/hooks/useAuth.ts` (+32 líneas)
+- `src/features/auth/components/LoginForm.tsx` (+78 líneas)
+
+#### Criterios de aceptación cumplidos
+- [x] Registro con email y contraseña funciona
+- [x] Validación de email duplicado retorna error claro
+- [x] Toast de éxito/error visible para el usuario
+
+#### Notas
+- Pendiente: agregar recovery de contraseña en siguiente iteración
+```
+
+### Template para crear un nuevo commit log
+
+```markdown
+## [v{version}] - {fecha}
+
+### Commit: {tipo}({modulo}): {descripción breve}
+**Hash:** {hash}
+**Fecha:** {fecha-hora}
+**Módulo:** {modulo}
+**Versión:** v{version}
+
+#### Cambios realizados
+- {cambio 1}
+- {cambio 2}
+- {cambio 3}
+
+#### Archivos modificados
+- `{ruta}` (+{líneas} líneas)
+- `{ruta}` (+{líneas} líneas)
+
+#### Criterios de aceptación cumplidos
+- [ ] {criterio 1}
+- [ ] {criterio 2}
+
+#### Notas
+{notas}
+```
+
+### Tipos de commit (Conventional Commits)
+
+| Tipo | Cuándo usarlo |
+|---|---|
+| `feat` | Nueva funcionalidad |
+| `fix` | Corrección de bug |
+| `refactor` | Cambio de estructura sin cambiar comportamiento |
+| `style` | Cambios de UI/CSS sin lógica nueva |
+| `docs` | Documentación |
+| `chore` | Configuración, dependencias, tooling |
+| `perf` | Optimización de rendimiento |
+| `test` | Agregar o modificar tests |
+
+---
+
+## 4. Sistema de Logs de Errores y Actividad
+
+> 💡 **Cuándo aplicar esta sección:** Los logs detallados están pensados para **proyectos con cliente o producción**. En prototipos y MVPs rápidos, usa solo `ACTIVIDAD/` (log diario) y salta `ERRORES/` hasta que el proyecto se estabilice. El objetivo es ayudar, no frenar.
+
+### Estructura de carpetas
+
+```
+docs/LOGS/
+├── INDEX.md                    # Índice de todos los logs
+├── ERRORES/                    # Errores organizados por tipo
+│   ├── AUTENTICACION/          # Errores de auth
+│   │   └── 2026-05-13-login-401.md
+│   ├── API/                    # Errores de peticiones HTTP
+│   │   └── 2026-05-13-supabase-timeout.md
+│   ├── UI/                     # Errores de renderizado / componentes
+│   │   └── 2026-05-13-modal-no-cierra.md
+│   ├── NATIVO/                 # Errores de Capacitor / Tauri
+│   │   └── 2026-05-13-camara-permiso-denegado.md
+│   ├── ESTADO/                 # Errores de estado global (Zustand/Redux)
+│   │   └── 2026-05-13-store-reset.md
+│   └── COMPILACION/            # Errores de build / TypeScript
+│       └── 2026-05-13-type-mismatch.md
+├── ACTIVIDAD/                  # Registro de actividad general
+│   ├── 2026-05/
+│   │   ├── 2026-05-13.md
+│   │   └── 2026-05-14.md
+│   └── INDEX.md
+└── FUNCIONALIDADES/            # Registro de funcionalidades implementadas
+    ├── modulo-auth.md
+    ├── modulo-dashboard.md
+    └── INDEX.md
+```
+
+### Formato para registro de error
+
+```markdown
+# Error: {Título descriptivo}
+
+**Fecha:** 2026-05-13 15:45
+**Tipo:** API / UI / NATIVO / ESTADO / COMPILACION
+**Severidad:** CRITICAL / HIGH / MEDIUM / LOW
+**Módulo:** auth / dashboard / products
+**Contexto:** {qué estaba haciendo el usuario o el sistema}
+
+## Descripción
+{Descripción clara del error}
+
+## Traza / Log
+```
+{stack trace o mensaje de error relevante}
+```
+
+## Causa raíz
+{qué lo provocó}
+
+## Solución aplicada
+{cómo se solucionó, con referencias a commits si aplica}
+
+## Prevención
+{cómo evitar que vuelva a ocurrir}
+
+## Archivos relacionados
+- `src/features/auth/services/AuthService.ts:45`
+```
+
+### Formato para registro de actividad
+
+```markdown
+# Actividad — 2026-05-13
+
+## Sesión de trabajo: Implementación de autenticación
+**Duración:** 14:00 - 17:30 (3.5h)
+**Objetivo:** Completar flujo de registro + login
+
+### Tareas realizadas
+1. ✅ Hook `useAuth` — lógica de sesión completa
+2. ✅ Componente `LoginForm` — validación y submit
+3. ⏳ `PasswordRecovery` — pendiente
+4. ❌ Tests de auth — pospuesto por error en mock
+
+### Errores encontrados
+- **Error #001** — Supabase timeout en registro (API)
+  → Solución: agregar retry con exponential backoff
+
+### Decisiones tomadas
+- Se usa Zustand en lugar de Context para auth state (mejor performance)
+
+### Próxima sesión
+- Completar `PasswordRecovery`
+- Escribir tests con Vitest
+```
+
+---
+
+### 4.1 Automatización de Logs con Scripts
+
+Para reducir la fricción y evitar que los logs se abandonen, se proveen scripts que automatizan parte del registro.
+
+#### Script: `scripts/log-error.sh`
+
+Genera un archivo de error con la estructura pre-llenada. Ubicar en `scripts/log-error.sh`:
+
+```bash
+#!/bin/bash
+# Uso: ./scripts/log-error.sh "Título del error" API HIGH auth
+
+TITLE="$1"
+TYPE="$2"
+SEVERITY="$3"
+MODULE="$4"
+DATE=$(date +%Y-%m-%d)
+TIME=$(date +%H:%M)
+FILENAME="docs/LOGS/ERRORES/${TYPE}/$(date +%Y-%m-%d)-$(echo $TITLE | tr '[:upper:]' '[:lower:]' | tr ' ' '-').md"
+
+mkdir -p "docs/LOGS/ERRORES/${TYPE}"
+
+cat > "$FILENAME" << EOF
+# Error: ${TITLE}
+
+**Fecha:** ${DATE} ${TIME}
+**Tipo:** ${TYPE}
+**Severidad:** ${SEVERITY}
+**Módulo:** ${MODULE}
+**Contexto:**
+
+## Descripción
+
+
+## Traza / Log
+\`\`\`
+
+\`\`\`
+
+## Causa raíz
+
+
+## Solución aplicada
+
+
+## Prevención
+
+
+## Archivos relacionados
+
+EOF
+
+echo "Log creado: $FILENAME"
+```
+
+#### Script: `scripts/log-commit.sh`
+
+Toma el último commit de git y genera la entrada en `docs/COMMITS/`:
+
+```bash
+#!/bin/bash
+# Uso: ./scripts/log-commit.sh
+
+HASH=$(git log -1 --format="%H")
+DATE=$(git log -1 --format="%ad" --date=short)
+MSG=$(git log -1 --format="%s")
+FILES=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD)
+VERSION=$(git tag --points-at HEAD | head -1)
+
+FILENAME="docs/COMMITS/${VERSION:-sin-version}-$(date +%Y%m%d).md"
+
+cat > "$FILENAME" << EOF
+## [${VERSION:-sin-version}] - ${DATE}
+
+### Commit: ${MSG}
+**Hash:** ${HASH}
+**Fecha:** ${DATE}
+**Módulo:**
+**Versión:** ${VERSION:-sin-version}
+
+#### Cambios realizados
+- $(echo "$MSG" | sed 's/^/\n- /')
+
+#### Archivos modificados
+$(echo "$FILES" | sed 's/^/- `/' | sed 's/$/`/')
+
+#### Criterios de aceptación cumplidos
+- [ ]
+
+#### Notas
+
+EOF
+
+echo "Commit log creado: $FILENAME"
+```
+
+#### Script: `scripts/log-actividad.sh`
+
+Inicia o continúa el log de actividad diaria:
+
+```bash
+#!/bin/bash
+# Uso: ./scripts/log-actividad.sh "Objetivo de la sesión"
+
+DATE=$(date +%Y-%m-%d)
+DIR="docs/LOGS/ACTIVIDAD/$(date +%Y-%m)"
+mkdir -p "$DIR"
+FILENAME="${DIR}/${DATE}.md"
+
+if [ ! -f "$FILENAME" ]; then
+  cat > "$FILENAME" << EOF
+# Actividad — ${DATE}
+
+## Sesión de trabajo: $1
+**Duración:**
+**Objetivo:** $1
+
+### Tareas realizadas
+1.
+
+### Errores encontrados
+
+### Decisiones tomadas
+
+### Próxima sesión
+
+EOF
+  echo "Log de actividad creado: $FILENAME"
+else
+  echo "Log ya existe: $FILENAME"
+  echo "Agrega manualmente las tareas al final del archivo."
+fi
+```
+
+> **Dar permisos de ejecución:** `chmod +x scripts/*.sh`
+
+### Estructura del backlog
+
+Cada proyecto debe tener `docs/BACKLOG/` con:
+
+```
+docs/BACKLOG/
+├── INDEX.md                    # Estado general del proyecto
+├── PHASE-1-core.md             # Fase 1: Funcionalidades núcleo
+├── PHASE-2-enhancement.md      # Fase 2: Mejoras
+├── PHASE-3-polish.md           # Fase 3: Pulido y optimización
+├── icebox.md                   # Ideas futuras (congeladas)
+└── progreso.json               # Tracking automatizado
+```
+
+### Distribución de prioridades por fase
+
+| Fase | Enfoque | % del proyecto | Prioridades |
+|---|---|---|---|
+| **PHASE-1 Core** | MVP funcional — lo mínimo indispensable | 50% | P0 (Crítico) |
+| **PHASE-2 Enhancement** | Características secundarias y UX | 30% | P1 (Importante) |
+| **PHASE-3 Polish** | Optimización, tests, accesibilidad | 20% | P2 (Deseable) |
+
+### Formato de tarea en backlog
+
+```markdown
+### [P0] TASK-001: Implementar login con email y contraseña
+**Módulo:** auth
+**Estimación:** 4h
+**Dependencias:** Ninguna
+**Criterios de aceptación:**
+- [ ] Formulario con validación de email (regex) y contraseña (mín 8 chars)
+- [ ] Llamada a Supabase Auth.signInWithPassword()
+- [ ] Manejo de error: "Credenciales inválidas" en rojo
+- [ ] Redirección a dashboard tras login exitoso
+- [ ] Perspectiva de testing: Vitest con mocks de Supabase
+
+**Notas:** Usar hook `useAuth` ya creado en scaffolding
+```
+
+### Regla de granularidad (Micro-Tasking)
+
+> **Cada tarea individual NO debe requerir más de 1-2 prompts a la IA.**
+> Si una tarea requiere más de 3 prompts, está mal dividida.
+
+Señales de que una tarea es demasiado grande:
+- La descripción tiene más de 3 criterios de aceptación
+- Involucra 3 o más archivos por crear
+- Mezcla UI + lógica de negocio + API
+- Requiere cambios en más de un módulo/feature
+
+---
+
+## 6. Reglas de Componentes y Modularización
+
+### Límites estrictos por archivo
+
+| Tipo de archivo | Límite máximo | Acción al superarlo |
+|---|---|---|
+| Componente UI (tsx) | **120 líneas** | Dividir en subcomponentes y extraer lógica a hooks |
+| Hook (ts/tsx) | **80 líneas** | Dividir en hooks más pequeños o mover lógica a utils |
+| Servicio (ts) | **150 líneas** | Separar por entidad o método |
+| Utilidad (ts) | **100 líneas** | Mover a archivo dedicado por función |
+| Feature Page (tsx) | **200 líneas** | Extraer secciones a componentes en `components/` |
+| Store (ts) | **100 líneas** | Dividir en slices por dominio |
+| Test (ts/tsx) | **150 líneas** | Separar por funcionalidad probada |
+
+### Reglas de separación automática
+
+Cuando un archivo supera el límite, se aplica este protocolo:
+
+1. **Identificar secciones claras**: Buscar bloques de código que puedan vivir independientemente (funciones, componentes hijos, tipos).
+2. **Extraer a archivo dedicado**: Mover a la carpeta correspondiente.
+3. **Actualizar imports**: El archivo original importa desde el nuevo archivo.
+4. **Registrar en commit log**: Documentar la refactorización.
+
+### Señales de que un componente debe dividirse
+
+- ✅ El componente tiene más de 3 estados visuales distintos
+- ✅ El JSX tiene más de 3 niveles de anidación profunda
+- ✅ Hay lógica condicional extensa (> 3 if/switch)
+- ✅ Se mezclan preocupaciones de negocio con presentación
+- ✅ El nombre del archivo incluye "Utils" o "Helpers" dentro del mismo componente
+- ✅ Hay fragmentos JSX que se repiten con variaciones menores
+
+### Ejemplo de mala vs buena modularización
+
+**INCORRECTO** — Todo en un archivo de 540 líneas:
+```tsx
+// ProfilePage.tsx — 540 líneas
+function ProfilePage() {
+  // 120 líneas de lógica de usuario
+  // 80 líneas de subcomponente de avatar
+  // 90 líneas de formulario de edición
+  // 70 líneas de listado de órdenes
+  // 180 líneas de JSX combinado
+}
+```
+
+**CORRECTO** — Separado en varios archivos:
+```tsx
+// features/profile/ProfilePage.tsx — 80 líneas (solo composición)
+// features/profile/components/ProfileHeader.tsx — 50 líneas
+// features/profile/components/ProfileForm.tsx — 90 líneas
+// features/profile/components/OrderList.tsx — 70 líneas
+// features/profile/hooks/useProfile.ts — 60 líneas
+```
+
+---
+
+## 7. Patrones React + Tailwind para Reutilización
+
+### Principios de reutilización
+
+1. **Composition > Inheritance**: Usar children, render props y compound components.
+2. **Custom hooks para lógica**: Extraer lógica repetitiva a hooks.
+3. **Componentes UI atómicos**: Crear primitivas en `components/ui/` con variantes (cva).
+4. **Tailwind utility-first**: Sin CSS personalizado. 100% Tailwind clases.
+5. **Tipado genérico**: Usar `<T>` en componentes de datos (tablas, listas, selects).
+
+### Patrón de componente UI reutilizable (shadcn-style)
+
+```tsx
+// components/ui/Button.tsx
+import { cva, type VariantProps } from "class-variance-authority"
+import { memo } from "react"
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        primary: "bg-blue-600 text-white hover:bg-blue-700",
+        secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
+        destructive: "bg-red-600 text-white hover:bg-red-700",
+        ghost: "hover:bg-gray-100 hover:text-gray-900",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "primary",
+      size: "default",
+    },
+  }
+)
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+const Button = memo<ButtonProps>(({ className, variant, size, ...props }) => (
+  <button className={buttonVariants({ variant, size, className })} {...props} />
+))
+Button.displayName = "Button"
+
+export { Button, buttonVariants }
+```
+
+### Patrón de custom hook genérico
+
+```tsx
+// hooks/useSupabaseTable.ts
+import { useState, useEffect } from "react"
+import { supabase } from "@/services/supabase/client"
+
+interface UseTableOptions<T> {
+  table: string
+  select?: string
+  filters?: Record<string, unknown>
+  order?: { column: string; ascending?: boolean }
+}
+
+interface UseTableResult<T> {
+  data: T[]
+  loading: boolean
+  error: string | null
+  refetch: () => void
+}
+
+export function useSupabaseTable<T>({
+  table,
+  select = "*",
+  filters,
+  order,
+}: UseTableOptions<T>): UseTableResult<T> {
+  const [data, setData] = useState<T[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  const fetchData = async () => {
+    setLoading(true)
+    setError(null)
+
+    let query = supabase.from(table).select(select)
+
+    if (filters) {
+      Object.entries(filters).forEach(([key, value]) => {
+        query = query.eq(key, value)
+      })
+    }
+
+    if (order) {
+      query = query.order(order.column, { ascending: order.ascending ?? true })
+    }
+
+    const { data: result, error: err } = await query
+
+    if (err) {
+      setError(err.message)
+    } else {
+      setData((result ?? []) as T[])
+    }
+    setLoading(false)
+  }
+
+  useEffect(() => { fetchData() }, [table, JSON.stringify(filters)])
+
+  return { data, loading, error, refetch: fetchData }
+}
+```
+
+### Patrón compound component (Select)
+
+```tsx
+// components/ui/Select.tsx
+import { createContext, useContext, useState, type ReactNode } from "react"
+
+interface SelectContextType {
+  value: string
+  onChange: (value: string) => void
+  open: boolean
+  setOpen: (open: boolean) => void
+}
+
+const SelectContext = createContext<SelectContextType | null>(null)
+
+function Select({ children, value, onChange }: { children: ReactNode; value: string; onChange: (v: string) => void }) {
+  const [open, setOpen] = useState(false)
+  return (
+    <SelectContext.Provider value={{ value, onChange, open, setOpen }}>
+      <div className="relative">{children}</div>
+    </SelectContext.Provider>
+  )
+}
+
+function Trigger({ children }: { children: ReactNode }) {
+  const ctx = useContext(SelectContext)!
+  return (
+    <button onClick={() => ctx.setOpen(!ctx.open)} className="flex h-10 w-full items-center justify-between rounded-md border px-3">
+      {children}
+      <span className="ml-2">{ctx.open ? "▲" : "▼"}</span>
+    </button>
+  )
+}
+
+function Options({ children }: { children: ReactNode }) {
+  const ctx = useContext(SelectContext)!
+  if (!ctx.open) return null
+  return (
+    <div className="absolute z-50 mt-1 w-full rounded-md border bg-white shadow-lg">
+      {children}
+    </div>
+  )
+}
+
+function Option({ value, children }: { value: string; children: ReactNode }) {
+  const ctx = useContext(SelectContext)!
+  return (
+    <button
+      onClick={() => { ctx.onChange(value); ctx.setOpen(false) }}
+      className={`w-full px-3 py-2 text-left hover:bg-gray-100 ${ctx.value === value ? "bg-blue-50 font-medium" : ""}`}
+    >
+      {children}
+    </button>
+  )
+}
+
+Select.Trigger = Trigger
+Select.Options = Options
+Select.Option = Option
+export { Select }
+```
+
+### Reglas de exportación (Barrel)
+
+Siempre usar archivos `index.ts` en cada carpeta para exportar solo lo público:
+
+```ts
+// components/ui/index.ts
+export { Button, buttonVariants } from "./Button"
+export { Input } from "./Input"
+export { Select } from "./Select"
+export { Card } from "./Card"
+```
+
+### Anti-patrones a evitar
+
+| ❌ Incorrecto | ✅ Correcto |
+|---|---|
+| `const MyComponent = (props: any)` | Tipar explícitamente con interfaz |
+| 3+ `useEffect` en un mismo componente | Unificar efectos o extraer a hook |
+| CSS modules o archivos `.css` sueltos | 100% Tailwind utility classes |
+| Props booleanas opcionales sin default | Usar defaultProps o valores por defecto |
+| Componente de 300+ líneas | Dividir en ≤120 líneas |
+| Funciones helper dentro del componente | Mover a `utils/` o al hook correspondiente |
+| `useState` para lógica compleja | Usar `useReducer` o Zustand |
+| Mezclar lógica de Capacitor y Tauri en mismo archivo | Separar por servicio |
+
+---
+
+## 8. Integración con react-doctor
+
+### ¿Qué es react-doctor?
+
+Es una herramienta de análisis estático que revisa tu código React en busca de:
+- Violaciones de reglas de hooks
+- Componentes demasiado grandes
+- Problemas de accesibilidad
+- Props no utilizadas
+- Renderizados innecesarios
+- Mejores prácticas de React
+
+### Integración en el flujo de trabajo
+
+```bash
+# Paso 1: Instalar
+npm install --save-dev react-doctor
+
+# Paso 2: Agregar script en package.json
+# "scripts": { "doctor": "react-doctor check ./src" }
+
+# Paso 3: Ejecutar antes de cada commit
+npm run doctor
+```
+
+### Configuración recomendada (.reactdoctorrc.json)
+
+```json
+{
+  "rules": {
+    "max-component-lines": { "severity": "warn", "limit": 120 },
+    "max-hook-lines": { "severity": "warn", "limit": 80 },
+    "no-complex-conditional-render": "error",
+    "no-unnecessary-fragment": "warn",
+    "prefer-early-return": "warn",
+    "no-large-bundles": "warn",
+    "hook-rules": "error",
+    "no-direct-mutation-state": "error",
+    "prefer-custom-hooks": { "severity": "warn", "min-usage": 2 }
+  }
+}
+```
+
+### Acción correctiva ante advertencias de react-doctor
+
+| Advertencia | Acción |
+|---|---|
+| "Component exceeds 120 lines" | Dividir en subcomponentes |
+| "Hook logic should be extracted" | Crear custom hook |
+| "Complex conditional render" | Extraer a variable o componente |
+| "Unused prop" | Eliminar o implementar |
+| "Hook usage outside rules" | Revisar orden y condiciones de hooks |
+
+---
+
+## 9. Estructura de Prompts — Correcto vs Incorrecto
+
+### Plantilla universal de prompt
+
+```
+## Contexto del proyecto
+{stack tecnológico, arquitectura, enlace a patrones de trabajo}
+
+## Objetivo específico
+{qué se necesita crear/modificar, una sola cosa}
+
+## Especificaciones técnicas
+{qué archivos crear, qué patrones usar, límites}
+
+## Reglas estrictas (must have)
+- [regla 1]
+- [regla 2]
+
+## Anti-patrones (prohibido)
+- [anti-patrón 1]
+- [anti-patrón 2]
+
+## Ejemplo correcto
+{código que sigue los patrones}
+
+## Ejemplo incorrecto
+{código que NO debe generarse}
+
+## Formato de salida esperado
+{estructura del output}
+```
+
+### Ejemplos de prompts correctos e incorrectos
+
+#### Contexto: Crear un hook de cámara con Capacitor
+
+**INCORRECTO (ambiguo):**
+```
+"Crea un hook para usar la cámara en React."
+```
+
+**CORRECTO (determinista):**
+```
+## Contexto
+Stack: React 18 + TypeScript + Capacitor 6 + Ionic 8.
+Convenciones: hooks en src/hooks/, un hook por archivo, máximo 80 líneas.
+Referencia: seguir patrón de hooks en docs/Framework de Desarrollo Asistido por IA.md.
+
+## Objetivo
+Crear el hook `useCapacitorCamera` que permita tomar fotos y obtener la URL de la imagen.
+
+## Especificaciones técnicas
+- Archivo: `src/hooks/useCapacitorCamera.ts`
+- Usar `@capacitor/camera` plugin
+- Retornar: `{ photo: string | null; takePhoto: () => Promise<void>; error: string | null }`
+- Manejar permisos denegados con mensaje claro
+- Máximo 60 líneas
+
+## Reglas estrictas
+- Tipar con TypeScript todas las funciones y estados
+- Manejar error si el permiso de cámara está denegado
+- Usar `Camera.getPhoto()` con opción `resultType: CameraResultType.Uri`
+
+## Anti-patrones (prohibido)
+- NO usar any
+- NO poner lógica de UI en el hook
+- NO mezclar con lógica de Tauri
+
+## Ejemplo correcto (parcial)
+```typescript
+interface UseCameraResult {
+  photo: string | null
+  takePhoto: () => Promise<void>
+  error: string | null
+}
+```
+
+## Ejemplo incorrecto
+```typescript
+// ❌ Sin tipos, sin manejo de errores, any por todos lados
+const useCamera = () => {
+  const [photo, setPhoto] = useState<any>(null)
+  const takePhoto = async () => {
+    const image = await Camera.getPhoto({ quality: 90 })
+    setPhoto(image)
+  }
+  return { photo, takePhoto }
+}
+```
+```
+
+#### Contexto: Crear un comando de Tauri para leer archivos
+
+**INCORRECTO (ambiguo):**
+```
+"Crea un comando de Tauri para leer archivos del sistema."
+```
+
+**CORRECTO (determinista):**
+```
+## Contexto
+Stack: Tauri v2 + Rust + React.
+Convenciones: comandos Tauri en src-tauri/src/commands/, llamados desde src/services/tauri/.
+
+## Objetivo
+Crear un comando Tauri `read_file_content` que lea un archivo de texto y devuelva su contenido.
+
+## Especificaciones técnicas
+- Comando Rust: `#[tauri::command] fn read_file_content(path: String) -> Result<String, String>`
+- Llamada desde frontend: `invoke('read_file_content', { path })`
+- Validar que el archivo existe antes de leer
+- Manejar error de permisos
+
+## Reglas estrictas
+- Tipado estricto en Rust (String, no &str)
+- No permitir path traversal (restringir a directorio de trabajo)
+- Devolver error legible en español
+
+## Anti-patrones (prohibido)
+- NO usar `std::fs::read_to_string` sin validar path
+- NO exponer comandos inseguros sin validación
+```
+
+### Trucos de comunicación con IA
+
+| Comando | Efecto | Cuándo usarlo |
+|---|---|---|
+| `/humano` | Hace que la IA responda de forma coloquial | Cuando necesitas explicaciones comprensibles |
+| `tldr` al final | Respuesta ultra concisa | Para obtener resumen ejecutivo |
+| `ELI5` | Explicación como si tuvieras 5 años | Conceptos complejos para principiantes |
+| `Listify` | Respuesta en formato de lista | Para pasos, requisitos, tareas |
+| `/sin-alucinar` | Fuerza a la IA a no inventar APIs que no existen | Cuando pides código que debe ser exacto |
+| `/validar` | Pide a la IA que valide su propia respuesta | Para verificar consistencia |
+| `formato: json` | Respuesta en JSON estructurado | Para exportar a sistemas externos |
+
+---
+
+## 10. Flujo de Trabajo Diario con IA
+
+### Ciclo de trabajo estándar
+
+```
+1. LEER → docs/Framework de Desarrollo Asistido por IA.md + docs/AGENTS.md
+2. PLANIFICAR → Revisar backlog (docs/BACKLOG/PHASE-*.md)
+3. PROMPTEAR → Usar plantilla de prompt (sección 9)
+4. IMPLEMENTAR → Aplicar código generado
+5. VERIFICAR → Ejecutar react-doctor + linter + tests
+6. DOCUMENTAR → Registrar en docs/COMMITS/ + docs/LOGS/ACTIVIDAD/
+7. REPETIR → Siguiente tarea del backlog
+```
+
+### CheckList pre-prompt
+
+Antes de enviar un prompt a la IA, verificar:
+
+- [ ] ¿El prompt incluye el stack tecnológico?
+- [ ] ¿La tarea es una sola funcionalidad atómica?
+- [ ] ¿Se especificaron los archivos a crear/modificar?
+- [ ] ¿Se dieron ejemplos correctos e incorrectos?
+- [ ] ¿Se listaron los anti-patrones a evitar?
+- [ ] ¿El prompt referencia este archivo como guía?
+
+### CheckList post-implementación
+
+- [ ] ¿Corre el pipeline de validación? (`./scripts/validate.sh`)
+- [ ] ¿El código pasa `npm run doctor`?
+- [ ] ¿El componente está dentro del límite de líneas?
+- [ ] ¿Los tipos TypeScript están correctos?
+- [ ] ¿Se documentó en el commit log?
+- [ ] ¿Se registró en el log de actividad (o se usó `scripts/log-actividad.sh`)?
+- [ ] ¿Se actualizó el progreso en el backlog?
+
+### Integración con el ecosistema de la metodología
+
+Esta guía se complementa con las fases definidas en el índice general:
+
+| Si estás en... | Usa este archivo para... |
+|---|---|---|
+| Fase 5 (Scaffolding) | Estructura de carpetas y creación de esqueletos |
+| Fase 6 (Backlog) | Distribución de prioridades, micro-tasking y asignación de perfil |
+| Fase 7 (Desarrollo activo) | Commits, logs, react-doctor, pipeline de validación y modularización |
+| Fase 8 (Entrega) | Phase Gates y retrospectiva |
+| Cualquier fase | Estructura de prompts y ejemplos correctos/incorrectos |
+
+---
+
+## 11. Pipeline de Validación Automática
+
+> 💡 **Cuándo aplicar esta sección:** Recomendado para todo proyecto que pase a producción. En prototipos rápidos, basta con ejecutar lint + typecheck manualmente. El pipeline completo (con tests y build) se activa cuando el proyecto tiene clientes o usuarios reales.
+
+### Propósito
+
+Garantizar que todo el código generado por IA pase filtros automáticos antes de llegar al repositorio. Esto evita que errores de tipo, lógica o estilo se acumulen.
+
+### Pipeline mínimo pre-commit
+
+Ejecutar en orden antes de cada commit:
+
+```bash
+# 1. Linter (ESLint con reglas estrictas)
+npm run lint -- --max-warnings=0
+
+# 2. TypeScript check (strict mode)
+npx tsc --noEmit
+
+# 3. react-doctor (auditoría de buenas prácticas)
+npx react-doctor check ./src
+
+# 4. Tests rápidos (solo unitarios, sin build)
+npm run test -- --run
+
+# 5. Build seco (verifica que compila)
+npm run build
+```
+
+### Script de validación unificado
+
+Crear `scripts/validate.sh`:
+
+```bash
+#!/bin/bash
+set -e
+
+echo "=== Pipeline de Validación ==="
+
+echo "[1/5] Linting..."
+npm run lint -- --max-warnings=0 || { echo "❌ Lint falló"; exit 1; }
+
+echo "[2/5] TypeScript check..."
+npx tsc --noEmit || { echo "❌ TypeScript falló"; exit 1; }
+
+echo "[3/5] react-doctor..."
+npx react-doctor check ./src || { echo "❌ react-doctor encontró problemas"; exit 1; }
+
+echo "[4/5] Tests..."
+npm run test -- --run || { echo "❌ Tests fallaron"; exit 1; }
+
+echo "[5/5] Build..."
+npm run build || { echo "❌ Build falló"; exit 1; }
+
+echo "=== ✅ Pipeline completo — Código válido ==="
+```
+
+```bash
+chmod +x scripts/validate.sh
+# Ejecutar antes de cada commit:
+./scripts/validate.sh
+```
+
+### Integración con husky (opcional)
+
+```bash
+npm install --save-dev husky lint-staged
+npx husky init
+```
+
+Crear `.husky/pre-commit`:
+
+```bash
+#!/usr/bin/env sh
+./scripts/validate.sh
+```
+
+### Archivo de referencia `docs/PIPELINE.md`
+
+Crear este archivo como documentación del pipeline para que la IA lo referencie:
+
+```markdown
+# Pipeline de Validación
+
+Este proyecto ejecuta validación automática antes de cada commit.
+
+## Pasos
+1. ESLint (0 warnings tolerados)
+2. TypeScript strict check
+3. react-doctor
+4. Vitest (unit tests)
+5. Build seco
+
+## Script
+`./scripts/validate.sh`
+
+## Reglas
+- Si cualquier paso falla, el commit se rechaza
+- No usar `--force` ni `--no-verify` sin autorización explícita
+- Si el pipeline es muy lento (>30s), dividir en pre-commit (lint+typecheck) y CI (tests+build)
+```
+
+---
+
+## 12. Phase Gates — CheckList de Salida por Fase
+
+> 💡 **Cuándo aplicar esta sección:** Exclusivo para **proyectos con cliente y presupuesto definido**. En prototipos o proyectos personales, los phase gates son overkill. Úsalos cuando necesites controlar alcance y evitar que el cliente se desvíe.
+
+### Propósito
+
+Cada fase de la metodología debe completarse al 100% antes de avanzar a la siguiente. Estos checklists evitan arrastrar deuda técnica entre fases.
+
+### Fase 1 → Fase 2 (Discovery → Historias de Usuario)
+
+- [ ] Se identificó el dolor principal del negocio
+- [ ] Se definieron los límites del alcance inicial
+- [ ] Se decidió ruta: desarrollo desde cero vs refactorización
+- [ ] El cliente aceptó la propuesta preliminar
+
+### Fase 2 → Fase 3 (Historias de Usuario → Prototipado)
+
+- [ ] Todas las historias de usuario siguen el formato determinista
+- [ ] Cada historia tiene actor, disparador, lógica, resultado esperado y resultado fallido
+- [ ] Las funciones críticas tienen su contrato de método definido
+- [ ] No hay ambigüedad en las reglas de negocio
+
+### Fase 3 → Fase 4 (Prototipado → Especificación con Cliente)
+
+- [ ] El prototipo visual es navegable (no solo imágenes estáticas)
+- [ ] Los componentes están modularizados para React (no páginas monolíticas)
+- [ ] 100% del diseño usa Tailwind (sin CSS personalizado)
+- [ ] Mobile-first probado en al menos 2 resoluciones
+
+### Fase 4 → Fase 5 (Especificación → Scaffolding)
+
+- [ ] **Go/No-Go completado** (checklist de aprobación de Fase 4)
+- [ ] Alcance congelado: no hay requerimientos nuevos sin cotizar
+- [ ] Presupuesto final aceptado por el cliente
+- [ ] Bibliotecas necesarias validadas técnicamente
+
+### Fase 5 → Fase 6 (Scaffolding → Backlog)
+
+- [ ] Estructura de carpetas creada según el estándar (sección 2)
+- [ ] Todos los archivos del scaffolding tienen `throw new Error("pendiente")` o equivalente
+- [ ] Los contratos de método (inputs/outputs/flujo) están completos en cada función esqueleto
+- [ ] El proyecto compila sin errores (`npm run build` pasa)
+- [ ] Los types/interfaces globales están definidos
+- [ ] Existe un `README.md` o `AGENTS.md` con el contexto del proyecto
+- [ ] `docs/COMMITS/INDEX.md` creado
+- [ ] `docs/LOGS/` estructura de carpetas creada
+- [ ] `docs/BACKLOG/` estructura de carpetas creada
+
+### Fase 6 → Fase 7 (Backlog → Desarrollo Activo)
+
+- [ ] Cada tarea P0 sigue el formato estándar (sección 5)
+- [ ] Ninguna tarea supera los límites de micro-tasking
+- [ ] Las dependencias entre tareas están mapeadas
+- [ ] Las tareas están ordenadas por capa: Datos → Backend → Frontend
+- [ ] No hay tareas sin criterios de aceptación claros
+- [ ] `progreso.json` creado y funcional
+
+### Fase 7 → Fase 8 (Desarrollo Activo → Entrega)
+
+- [ ] Todas las tareas P0 y P1 están completadas
+- [ ] Pipeline de validación pasa sin errores (sección 11)
+- [ ] react-doctor reporta 0 warnings críticos
+- [ ] Coverage de tests mínimo: 70%
+- [ ] Todos los errores CRITICAL y HIGH están documentados en `docs/LOGS/ERRORES/`
+- [ ] Commit logs están actualizados hasta el último cambio
+- [ ] Versión semántica actualizada según SemVer checklist
+- [ ] Se realizó la retrospectiva de la iteración (sección 13)
+
+### Fase 8 → Cierre (Entrega → Mantenimiento)
+
+- [ ] Acta de entrega firmada por el cliente
+- [ ] Manual de usuario entregado
+- [ ] Capacitación realizada
+- [ ] Políticas de soporte definidas y comunicadas
+- [ ] Repositorio limpiado (sin ramas muertas, sin archivos temporales)
+- [ ] Documentación final actualizada
+
+---
+
+## 13. Retrospectiva por Iteración
+
+> 💡 **Cuándo aplicar esta sección:** Útil después de **milestones importantes o entregas a cliente**. No la apliques después de cada sesión de código — solo cuando cierres una versión o fase completa. En side projects, la retrospectiva exprés de 4 preguntas basta.
+
+### Propósito
+
+Después de cada milestone o versión, se realiza una retrospectiva para ajustar la metodología de forma continua. Esto cierra el ciclo de mejora y evita repetir errores.
+
+### Template de retrospectiva
+
+Crear `docs/RETROSPECTIVA.md` y completarlo al cerrar cada versión:
+
+```markdown
+# Retrospectiva — v{x.x.x}
+
+**Fecha:** {dd/mm/aaaa}
+**Duración del ciclo:** {fecha inicio} → {fecha fin}
+**Participantes:** {quien trabajó en el ciclo}
+
+---
+
+### 1. ¿Qué funcionó bien?
+- {ej: el micro-tasking evitó que la IA alucinara}
+- {ej: los phase gates detectaron scaffolding incompleto a tiempo}
+
+### 2. ¿Qué no funcionó o costó más de lo esperado?
+- {ej: los prompts para el hook de cámara requirieron 4 intentos}
+- {ej: el pipeline de validación tardaba demasiado}
+
+### 3. ¿Hubo algo que la IA alucinó repetidamente?
+- {ej: inventó APIs de Capacitor que no existen}
+- {ej: no respetó el límite de 120 líneas en componentes}
+
+### 4. ¿Qué ajuste harías en la metodología para la próxima iteración?
+- {ej: agregar un anti-patrón explícito para ese caso en la sección 9}
+- {ej: reducir el límite de líneas a 100 para hooks}
+
+### 5. Acción concreta para el próximo ciclo
+- [ ] {acción 1: ej: actualizar Framework de Desarrollo Asistido por IA.md con el nuevo anti-patrón}
+- [ ] {acción 2: ej: crear un prompt template específico para hooks de Capacitor}
+- [ ] {acción 3: ej: optimizar el pipeline para que corra en paralelo}
+```
+
+### Recordatorio en el backlog
+
+Agregar al final de cada milestone en `docs/BACKLOG/PHASE-*.md`:
+
+```markdown
+### 🎯 Post-milestone
+- [ ] Ejecutar retrospectiva → `docs/RETROSPECTIVA.md`
+- [ ] Actualizar `Framework de Desarrollo Asistido por IA.md` según hallazgos
+- [ ] Ajustar `progreso.json` con métricas reales vs estimadas
+```
+
+### Preguntas rápidas para retrospectivas exprés
+
+Cuando no hay tiempo para la retrospectiva completa:
+
+| Pregunta | Respuesta |
+|---|---|
+| ¿Qué repetirías? | |
+| ¿Qué no repetirías? | |
+| ¿Qué harías diferente? | |
+| ¿Qué aprendiste sobre la IA? | |
+
+---
+
+## 14. Perfiles de Desarrollador
+
+> 💡 **Cuándo aplicar esta sección:** Si trabajas solo, ignora esta sección y define tu perfil como **Senior** en `AGENTS.md`. Los niveles Junior/Mid están pensados para **equipos** o para cuando delegas tareas a otro desarrollador. Si eres el único dev, las reglas extra de perfiles no agregan valor.
+
+### Propósito
+
+No todos los desarrolladores tienen el mismo nivel de experiencia. Esta sección adapta el nivel de detalle de los prompts, scaffolds y reglas según el perfil.
+
+### Tabla de perfiles
+
+| Perfil | Descripción | Detalle en prompts | Scaffolding | Autonomía |
+|---|---|---|---|---|
+| **Junior** | Poca experiencia con el stack o con IA | Máximo detalle: ejemplos completos, prohibiciones explícitas, estructura archivo por archivo | Templates completos con 80% del código escrito | Revisión obligatoria de cada archivo generado |
+| **Mid** | Experiencia moderada (1-2 años con el stack) | Detalle medio: firma de funciones + reglas, ejemplos parciales | Contratos de método + interfaces + firmas vacías | Revisión por lotes (cada 3-4 archivos) |
+| **Senior** | Domina el stack y la metodología | Mínimo necesario: objetivo + restricciones + anti-patrones | Solo contratos de alto nivel, sin código base | Confianza para revisar al final del módulo |
+
+### Nivel Junior — Reglas adicionales
+
+```
+## Reglas para perfil Junior
+
+### En los prompts:
+- Incluir SIEMPRE ejemplos correctos E incorrectos completos
+- Especificar la ruta exacta de cada archivo a crear
+- Definir tipos e interfaces antes de pedir la implementación
+- Incluir los imports necesarios en los ejemplos
+- Pedir a la IA que explique cada decisión con comentarios
+
+### En el scaffolding:
+Usar el nivel máximo de detalle:
+```tsx
+// components/ui/Button.tsx
+import { cva, type VariantProps } from "class-variance-authority"
+// + todo el código completo del ejemplo en sección 7
+
+// hooks/useAuth.ts
+export function useAuth() {
+  // 1. Obtener sesión de Supabase
+  // 2. Retornar { user, login, logout, loading }
+  // 3. Manejar error de sesión expirada
+  throw new Error("Lógica pendiente")
+}
+```
+
+### En la validación:
+- Ejecutar el pipeline completo (sección 11) después de CADA archivo
+- No avanzar hasta que react-doctor dé 0 warnings
+- Documentar cada error en `docs/LOGS/ERRORES/` inmediatamente
+```
+
+### Nivel Mid — Reglas adicionales
+
+```
+## Reglas para perfil Mid
+
+### En los prompts:
+- Incluir firma completa de funciones (tipos de entrada y salida)
+- Especificar archivos pero no rutas exactas (el desarrollador decide)
+- Incluir anti-patrones pero no ejemplos completos de código incorrecto
+
+### En el scaffolding:
+Usar nivel medio:
+```tsx
+// features/auth/services/AuthService.ts
+interface RegisterDTO { email: string; password: string; name: string }
+interface LoginDTO { email: string; password: string }
+interface AuthResult { token: string; user: UserProfile }
+
+export async function register(dto: RegisterDTO): Promise<AuthResult>
+export async function login(dto: LoginDTO): Promise<AuthResult>
+export async function logout(): Promise<void>
+// + contrato de método con flujo esperado
+```
+
+### En la validación:
+- Ejecutar pipeline por feature completa (no archivo por archivo)
+- react-doctor: 0 errors, warnings tolerados si están justificados
+- Revisar logs de errores al final del día
+```
+
+### Nivel Senior — Reglas adicionales
+
+```
+## Reglas para perfil Senior
+
+### En los prompts:
+- Solo objetivo + contexto + restricciones técnicas
+- La IA recibe libertad para sugerir estructuras y patrones
+- El desarrollador corrige sobre la marcha sin necesidad de ejemplos
+
+### En el scaffolding:
+Usar nivel mínimo:
+```tsx
+// features/payments/services/PaymentService.ts
+// Contrato:
+// - registerPayment(dto) → valida tarjeta, cobra, registra transacción, notifica
+// - refund(transactionId) → valida estado, revierte cargo, actualiza BD
+// Impacto: fallo aquí bloquea checkout y reportes contables
+```
+
+### En la validación:
+- Pipeline completo solo al final del módulo
+- react-doctor como referencia, no como gatekeeper
+- Los errores se documentan solo si son recurrentes
+```
+
+### Asignación de perfil por proyecto
+
+Al iniciar un proyecto, definir el perfil en `AGENTS.md`:
+
+```markdown
+## Perfil del desarrollador
+Senior / Mid / Junior
+```
+
+Esto le indica a la IA qué nivel de detalle usar en sus respuestas sin necesidad de cambiar el prompt cada vez.
+
+### Progresión de perfiles
+
+A medida que el desarrollador gana confianza, puede subir de perfil:
+
+```
+Junior → Mid: Cuando completa 3 features sin errores críticos
+Mid → Senior: Cuando completa 1 proyecto completo y comienza a ajustar la metodología
+```
+
+---
+
+## 15. Biblioteca de Prompts (docs/PROMPTS/)
+
+> 💡 **Cuándo aplicar:** Siempre que inicies un nuevo archivo o feature. La biblioteca contiene prompts pre-armados para tareas recurrentes. Copia, pega y ajusta los `{placeholders}`.
+
+### Estructura de la biblioteca
+
+```
+docs/PROMPTS/
+├── INDEX.md                       ← Índice completo con metadatos
+├── PLANTILLAS/                    ← Prompts genéricos reutilizables
+│   ├── 01-hook-supabase.md        ← useSupabaseTable<T>
+│   ├── 02-componente-ui.md        ← Button con cva
+│   ├── 03-pagina-feature.md       ← FeaturePage por composición
+│   ├── 04-comando-tauri.md        ← Comando Tauri Rust + TS
+│   ├── 05-store-zustand.md        ← Store con Zustand
+│   ├── 06-servicio-supabase.md    ← CRUD service con errores
+│   ├── 07-formulario-validacion.md ← react-hook-form + zod
+│   ├── 08-hook-capacitor.md       ← useCapacitorCamera
+│   ├── 09-refactor-division.md    ← Split componente grande
+│   └── 10-scaffolding-inicial.md  ← Setup feature completo
+├── STACK/                         ← Contextos por tecnología
+│   ├── react-web-puro.md          ← Web React + Supabase
+│   ├── ionic-capacitor.md         ← Mobile Ionic + Capacitor
+│   └── tauri-desktop.md           ← Desktop Tauri v2
+└── HISTORIAL/                     ← Prompts archivados post-uso
+```
+
+### Cómo usar
+
+Cada prompt sigue el formato determinista de la sección 9:
+
+<details>
+<summary>📁 Ejemplo: 01-hook-supabase.md</summary>
+
+```
+## Contexto
+Stack: React 18 + TypeScript + Vite + Supabase.
+Convenciones: hooks en src/hooks/, un hook por archivo, máximo 80 líneas.
+Patrón: hook genérico con <T> para tipado dinámico.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 7.
+
+## Objetivo
+Crear el hook `useSupabaseTable<T>` que haga CRUD a una tabla de Supabase.
+
+## Especificaciones técnicas
+- Archivo: `src/hooks/useSupabaseTable.ts`
+- Retornar: `{ data: T[]; loading: boolean; error: string | null; refetch: () => void }`
+- Máximo 65 líneas
+
+## Reglas estrictas
+- Tipar con genéricos `<T>`
+- `loading` debe iniciar en `true`
+- `error` debe ser `string | null`
+
+## Anti-patrones
+- NO usar any
+- NO mezclar UI en el hook
+- NO hacer fetch en el render
+
+## Ejemplo incorrecto
+```typescript
+function useTable(table: string) {
+  const [data, setData] = useState<any[]>([])
+  useEffect(() => { supabase.from(table).select("*").then(setData) }, [])
+  return data
+}
+```
+
+## Formato de salida
+Archivo completo listo para copiar a `src/hooks/useSupabaseTable.ts`.
+```
+</details>
+
+<details>
+<summary>📁 Ejemplo: 05-store-zustand.md</summary>
+
+```
+## Contexto
+Stack: React 18 + TypeScript + Zustand.
+Convenciones: stores en src/store/, un store por dominio, máx 100 líneas.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 2.
+
+## Objetivo
+Crear el store Zustand `{name}Store` para {descripción del dominio}.
+
+## Especificaciones técnicas
+- Archivo: `src/store/{name}Store.ts`
+- Estado: {propiedades del estado}
+- Acciones: {set, reset, fetch, etc.}
+- Integrar con {servicio externo si aplica}
+
+## Reglas estrictas
+- Tipar todo con interfaces
+- Acciones inmutables (spread o immer)
+- Acciones async deben manejar loading/error
+
+## Anti-patrones
+- NO mutar estado directamente
+- NO poner lógica de UI en el store
+- NO duplicar estado que ya existe en BD
+
+## Ejemplo parcial
+```typescript
+interface AuthState {
+  user: User | null
+  loading: boolean
+  login: (email: string, password: string) => Promise<void>
+  logout: () => void
+}
+```
+
+## Formato de salida
+Archivo completo listo para `src/store/{name}Store.ts`.
+```
+</details>
+
+<details>
+<summary>📁 Ejemplo: 04-comando-tauri.md</summary>
+
+```
+## Contexto
+Stack: Tauri v2 + Rust + React + TypeScript.
+Convenciones: comandos Rust en src-tauri/src/commands/, wrappers en src/services/tauri/.
+Referencia: docs/Framework de Desarrollo Asistido por IA.md sección 1.
+
+## Objetivo
+Crear el comando Tauri `{command_name}` que {descripción}.
+
+## Especificaciones técnicas
+Archivos:
+- `src-tauri/src/commands/{command_name}.rs` (Rust)
+- `src-tauri/src/main.rs` (registrar comando)
+- `src/services/tauri/{command_name}.ts` (wrapper TS)
+
+Comando Rust:
+- #[tauri::command]
+- fn {name}({params}) -> Result<{output}, String>
+- Validar inputs antes de ejecutar
+
+## Reglas estrictas
+- Tipado estricto (String, no &str)
+- No permitir path traversal
+- Devolver error específico en español
+
+## Anti-patrones
+- NO std::fs::read_to_string sin validar path
+- NO exponer comandos inseguros
+
+## Formato de salida
+Código Rust + wrapper TypeScript + instrucción de registro.
+```
+</details>
+
+### Reglas de la biblioteca
+
+1. **Un prompt por archivo.** Si cubre dos cosas distintas, se divide.
+2. **Metadatos** (title, tags, usado_en, fecha) al inicio de cada archivo.
+3. **Solo se archiva lo probado.** Si no se usó en un proyecto real, no se agrega.
+4. **Los fallos también se guardan** en `HISTORIAL/` con nota de por qué no funcionó.
+5. **Para crear un nuevo prompt:** copia cualquier PLANTILLA, ajusta el contenido, renómbralo y agrega la entrada en `docs/PROMPTS/INDEX.md`.
+
+> 📌 **Referencia rápida:** `docs/PROMPTS/INDEX.md` tiene el índice completo con descripciones y metadatos de cada prompt disponible.
+
+---
+
+```markdown
+# AGENTS.md — Contexto para IA
+
+## Stack
+- React 18 + TypeScript + Vite
+- Ionic 8 + Capacitor 6 (mobile)
+- Tauri v2 (desktop)
+- Tailwind CSS 3.4
+- Zustand (estado global)
+- Supabase (backend)
+
+## Convenciones
+- Un componente por archivo, máximo 120 líneas
+- Un hook por archivo, máximo 80 líneas
+- 100% Tailwind utility classes (sin CSS personalizado)
+- Barrel exports en cada carpeta
+- Commits: conventional commits + log en docs/COMMITS/
+- Errores: registrar en docs/LOGS/ERRORES/
+- Backlog: docs/BACKLOG/PHASE-*.md
+- Prompt library: docs/PROMPTS/INDEX.md (usar para tareas comunes)
+
+## Perfil del desarrollador
+{Junior / Mid / Senior}
+
+## Reglas críticas
+- NO mezclar lógica de Capacitor con Tauri en el mismo archivo
+- NO usar any
+- NO superar límites de líneas sin refactorizar
+- Ejecutar pipeline de validación antes de cada commit (./scripts/validate.sh)
+
+## Referencias
+- Patrones detallados: docs/Framework de Desarrollo Asistido por IA.md
+- Prompt library: docs/PROMPTS/INDEX.md
+- Pipeline: docs/PIPELINE.md
+- Retrospectiva: docs/RETROSPECTIVA.md
+- Metodología completa: Metodologia_De_Desarrollo_IA_Asisted/
+```
+
+> **Este archivo es el punto de entrada para la IA.** Cada prompt debe comenzar con "Revisa AGENTS.md y Framework de Desarrollo Asistido por IA.md antes de responder."