javi-forge 0.1.0

package/ai-config/agents/specialized/solo-dev-planner-modular/02-SELF-CORRECTION.md

@@ -0,0 +1,778 @@
+---
+name: solo-dev-planner-self-correction
+description: "Módulo 2: Auto-fix y context management"
+---
+
+# 🔄 Solo Dev Planner - Self-Correction & Context Management
+
+> Módulo 2 de 6: Autonomía del agente con auto-fix y context optimizado
+
+## 📚 Relacionado con:
+- 01-CORE.md (Filosofía base)
+- 03-PROGRESSIVE-SETUP.md (Usa estos scripts en setup)
+- 06-OPERATIONS.md (Mise tasks)
+
+---
+
+## 🔄 Self-Correction Protocol (Autonomía del Agente)
+
+### Filosofía: El Agente Como Solucionador Autónomo
+
+**Problema tradicional:**
+```typescript
+❌ Test falla → Agente se detiene → Espera humano
+❌ Lint error → Agente pide ayuda → Pierde contexto
+❌ Build falla → Agente confused → Workflow bloqueado
+```
+
+**Con Self-Correction:**
+```typescript
+✅ Error detectado → Lee error → Analiza causa → Aplica fix → Re-ejecuta
+✅ Hasta 3 intentos automáticos antes de pedir ayuda humana
+✅ Aprende de errores comunes y los evita
+```
+
+### Script Completo de Auto-Fix
+
+```bash
+#!/bin/bash
+# scripts/auto-fix.sh - Auto-corrección inteligente completa
+
+set -e
+
+ERROR_TYPE=$1
+MAX_ATTEMPTS=3
+ATTEMPT=0
+
+# Colores para output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_attempt() {
+  echo "$(date -Iseconds)|$ATTEMPT|$ERROR_TYPE|$1" >> .auto-fix-log.txt
+}
+
+auto_fix_lint() {
+  echo -e "${YELLOW}🔧 Auto-fixing lint errors...${NC}"
+  
+  mise run format
+  mise run lint --fix
+  
+  if mise run lint; then
+    echo -e "${GREEN}✅ Lint fixed${NC}"
+    return 0
+  else
+    echo -e "${RED}❌ Lint still failing${NC}"
+    return 1
+  fi
+}
+
+auto_fix_imports() {
+  echo -e "${YELLOW}🔧 Auto-fixing import errors...${NC}"
+  
+  if [ -f "package.json" ]; then
+    bun install
+  elif [ -f "pyproject.toml" ]; then
+    uv sync
+  elif [ -f "go.mod" ]; then
+    go mod tidy
+  elif [ -f "Cargo.toml" ]; then
+    cargo fetch
+  fi
+  
+  return 0
+}
+
+auto_fix_database() {
+  echo -e "${YELLOW}🔧 Auto-fixing database errors...${NC}"
+  
+  mise run docker:up
+  echo "⏳ Waiting for database..."
+  sleep 5
+  
+  mise run db:migrate
+  
+  if psql "$DATABASE_URL" -c "SELECT 1" > /dev/null 2>&1; then
+    echo -e "${GREEN}✅ Database fixed${NC}"
+    return 0
+  else
+    echo -e "${RED}❌ Database still not responding${NC}"
+    return 1
+  fi
+}
+
+auto_fix_tests() {
+  echo -e "${YELLOW}🔧 Auto-fixing test errors...${NC}"
+  
+  rm -rf .cache coverage .pytest_cache
+  
+  if [ "$NODE_ENV" != "production" ]; then
+    mise run db:reset
+  fi
+  
+  if mise run test:unit; then
+    echo -e "${GREEN}✅ Tests fixed${NC}"
+    return 0
+  else
+    echo -e "${RED}❌ Tests still failing${NC}"
+    return 1
+  fi
+}
+
+auto_fix_types() {
+  echo -e "${YELLOW}🔧 Attempting to fix type errors...${NC}"
+  
+  if [ -f "tsconfig.json" ]; then
+    bun run build || true
+  elif [ -f "pyproject.toml" ]; then
+    pyright --createstub || true
+  fi
+  
+  return 0
+}
+
+# Main loop con retry logic
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+  ATTEMPT=$((ATTEMPT + 1))
+  echo -e "\n${YELLOW}🔄 Fix attempt $ATTEMPT/$MAX_ATTEMPTS${NC}"
+  
+  if case "$ERROR_TYPE" in
+    lint)      auto_fix_lint ;;
+    imports)   auto_fix_imports ;;
+    database)  auto_fix_database ;;
+    tests)     auto_fix_tests ;;
+    types)     auto_fix_types ;;
+    *)         echo -e "${RED}❌ Unknown error type: $ERROR_TYPE${NC}"; exit 1 ;;
+  esac; then
+    log_attempt "SUCCESS"
+    echo -e "${GREEN}✅ Fixed after $ATTEMPT attempts${NC}"
+    exit 0
+  fi
+  
+  log_attempt "FAILED"
+  
+  if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+    echo "⏳ Waiting 2 seconds before retry..."
+    sleep 2
+  fi
+done
+
+echo -e "\n${RED}⛔ BLOCKED: Could not auto-fix after $MAX_ATTEMPTS attempts${NC}"
+echo -e "${YELLOW}🙋 Human intervention required${NC}"
+log_attempt "BLOCKED"
+exit 1
+```
+
+### Mise Tasks con Auto-Recovery
+
+```toml
+# .mise.toml - Tasks mejorados con auto-recovery
+
+[tasks."fix:auto"]
+description = "Auto-detect and fix common errors"
+run = """
+#!/usr/bin/env bash
+
+LAST_ERROR=$(cat .last-error 2>/dev/null || echo "")
+
+if echo "$LAST_ERROR" | grep -qi "lint\|format\|prettier"; then
+  bash scripts/auto-fix.sh lint
+elif echo "$LAST_ERROR" | grep -qi "import\|module\|cannot find"; then
+  bash scripts/auto-fix.sh imports
+elif echo "$LAST_ERROR" | grep -qi "database\|postgres\|connection"; then
+  bash scripts/auto-fix.sh database
+elif echo "$LAST_ERROR" | grep -qi "test.*failed\|assertion"; then
+  bash scripts/auto-fix.sh tests
+elif echo "$LAST_ERROR" | grep -qi "type.*error"; then
+  bash scripts/auto-fix.sh types
+else
+  echo "❓ No auto-fix available for this error"
+  exit 1
+fi
+"""
+
+[tasks.test]
+description = "Run tests with auto-recovery"
+run = """
+#!/usr/bin/env bash
+
+ATTEMPT=0
+MAX_ATTEMPTS=2
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+  ATTEMPT=$((ATTEMPT + 1))
+  
+  if mise run test:unit 2>&1 | tee .last-error; then
+    echo "✅ Tests passed"
+    exit 0
+  fi
+  
+  echo "⚠️ Tests failed, attempt $ATTEMPT/$MAX_ATTEMPTS"
+  
+  if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+    echo "Attempting auto-fix..."
+    bash scripts/auto-fix.sh tests || true
+  fi
+done
+
+echo "❌ Tests still failing after auto-fix"
+exit 1
+"""
+```
+
+### Git Hooks con Recovery Automático
+
+```toml
+# .mise.toml - Hooks con auto-fix
+
+[hooks.pre-commit]
+run = """
+#!/usr/bin/env bash
+set -e
+
+echo "🎣 Running pre-commit hooks..."
+
+# Lint con auto-fix automático
+if ! mise run lint 2>&1 | tee .last-error; then
+  echo "⚠️ Lint failed, attempting auto-fix..."
+  
+  if bash scripts/auto-fix.sh lint; then
+    echo "✅ Auto-fixed and re-staged"
+    git add -u
+  else
+    echo "❌ Could not auto-fix. Please fix manually."
+    exit 1
+  fi
+fi
+
+# Tests con auto-recovery (2 intentos)
+ATTEMPT=0
+while [ $ATTEMPT -lt 2 ]; do
+  if mise run test:changed; then
+    echo "✅ Tests passed"
+    break
+  fi
+  
+  ATTEMPT=$((ATTEMPT + 1))
+  if [ $ATTEMPT -lt 2 ]; then
+    echo "Attempting test auto-fix..."
+    bash scripts/auto-fix.sh tests || true
+  else
+    echo "❌ Tests failing after auto-fix"
+    exit 1
+  fi
+done
+
+echo "✅ Pre-commit checks passed!"
+"""
+```
+
+---
+
+## 📊 Context Script (Para Claude Code)
+
+### Problema: Context Window Pollution
+
+**Sin Context Script:**
+```
+Claude Code debe leer:
+❌ 50+ archivos para entender estado
+❌ 10,000+ tokens consumidos
+❌ Lento y costoso
+❌ Pierde contexto entre turnos
+```
+
+**Con Context Script:**
+```
+Claude Code ejecuta:
+✅ 1 comando → Estado completo
+✅ < 500 tokens
+✅ JSON parseable
+✅ Rápido y barato
+```
+
+### Implementación Completa
+
+```bash
+#!/bin/bash
+# scripts/agent-context.sh
+# Proporciona estado completo del proyecto en < 500 tokens
+
+cat << EOF
+{
+  "timestamp": "$(date -Iseconds)",
+  "git": {
+    "branch": "$(git branch --show-current)",
+    "status": "$(git status -s | wc -l) files changed",
+    "last_commit": "$(git log -1 --pretty=format:'%h - %s (%ar)')",
+    "unpushed": $(git log origin/$(git branch --show-current)..HEAD --oneline 2>/dev/null | wc -l)
+  },
+  "tools": {
+    "node": "$(mise current node 2>/dev/null || echo 'not installed')",
+    "python": "$(mise current python 2>/dev/null || echo 'not installed')",
+    "go": "$(mise current go 2>/dev/null || echo 'not installed')"
+  },
+  "tests": {
+    "status": "$(mise run test:unit >/dev/null 2>&1 && echo 'passing' || echo 'failing')",
+    "coverage": "$(grep -oP '\d+%' coverage.txt 2>/dev/null | head -1 || echo 'unknown')",
+    "last_run": "$(stat -f '%Sm' -t '%Y-%m-%d %H:%M' .last-test 2>/dev/null || echo 'never')"
+  },
+  "database": {
+    "migrations": $(ls migrations/*.sql 2>/dev/null | wc -l),
+    "pending": $(mise run db:status 2>/dev/null | grep -c 'pending' || echo 0),
+    "connection": "$(psql "$DATABASE_URL" -c 'SELECT 1' >/dev/null 2>&1 && echo 'ok' || echo 'failed')"
+  },
+  "build": {
+    "lint": "$(mise run lint >/dev/null 2>&1 && echo 'passing' || echo 'failing')",
+    "last_error": "$(tail -n 3 .last-error 2>/dev/null || echo 'none')"
+  },
+  "todos": [
+    $(grep -r "TODO\|FIXME" src/ 2>/dev/null | head -n 5 | sed 's/"/\\"/g' | awk '{print "    \"" $0 "\""}' | paste -sd,)
+  ],
+  "phase": "$([ -f docker-compose.yml ] && echo 'alpha' || echo 'mvp')",
+  "health": {
+    "api_running": $(curl -s http://localhost:8080/health >/dev/null 2>&1 && echo 'true' || echo 'false'),
+    "db_running": $(docker ps | grep -q postgres && echo 'true' || echo 'false')
+  }
+}
+EOF
+```
+
+### Mise Integration
+
+```toml
+# .mise.toml
+
+[tasks.context]
+description = "Show complete project context (for AI agents)"
+run = "bash scripts/agent-context.sh"
+alias = "ctx"
+
+[tasks."context:watch"]
+description = "Watch context changes in real-time"
+run = "watch -n 2 'bash scripts/agent-context.sh | jq'"
+
+[tasks."context:save"]
+description = "Save context snapshot"
+run = "bash scripts/agent-context.sh > .context-snapshot-$(date +%s).json"
+```
+
+### Workflow para Claude Code
+
+```markdown
+# En cada turno, Claude Code ejecuta:
+
+```bash
+mise run context
+```
+
+# Output (< 500 tokens):
+```json
+{
+  "timestamp": "2025-12-23T15:30:00Z",
+  "git": {
+    "branch": "feat/01-user-auth",
+    "status": "3 files changed",
+    "last_commit": "abc123 - add User model (2 minutes ago)"
+  },
+  "tests": { "status": "failing", "coverage": "75%" },
+  "database": { "migrations": 3, "pending": 0 },
+  "build": { "lint": "passing" },
+  "phase": "mvp",
+  "health": { "api_running": false, "db_running": true }
+}
+```
+
+**El agente ahora sabe TODO sin leer archivos!** ✨
+```
+
+---
+
+##
+    imports)  auto_fix_imports && exit 0 ;;
+    database) auto_fix_database && exit 0 ;;
+    tests)    auto_fix_tests && exit 0 ;;
+  esac
+  
+  sleep 2
+done
+
+echo "⛔ BLOCKED: Could not auto-fix after $MAX_ATTEMPTS attempts"
+echo "🙋 Human intervention required"
+exit 1
+```
+
+### Categorías de Errores y Fixes Automáticos
+
+**1. Errores de Linting:**
+```bash
+❌ ESLint: Unexpected token
+→ mise run format && mise run lint --fix
+```
+
+**2. Errores de Imports:**
+```bash
+❌ Cannot find module '@/models/User'
+→ bun install (o uv sync, go mod tidy)
+```
+
+**3. Errores de Database:**
+```bash
+❌ Connection refused
+→ mise run docker:up && mise run db:migrate
+```
+
+**4. Errores de Tests:**
+```bash
+❌ Test failed
+→ rm -rf .cache && mise run test:unit
+```
+
+### Mise Tasks con Auto-Recovery
+
+```toml
+# .mise.toml
+
+[tasks."fix:auto"]
+description = "Auto-detect and fix common errors"
+run = """
+#!/usr/bin/env bash
+LAST_ERROR=$(cat .last-error 2>/dev/null || echo "")
+
+if echo "$LAST_ERROR" | grep -qi "lint"; then
+  bash scripts/auto-fix.sh lint
+elif echo "$LAST_ERROR" | grep -qi "import"; then
+  bash scripts/auto-fix.sh imports
+elif echo "$LAST_ERROR" | grep -qi "database"; then
+  bash scripts/auto-fix.sh database
+elif echo "$LAST_ERROR" | grep -qi "test"; then
+  bash scripts/auto-fix.sh tests
+fi
+"""
+
+[tasks.test]
+description = "Run tests with auto-recovery"
+run = """
+#!/usr/bin/env bash
+ATTEMPT=0
+MAX_ATTEMPTS=2
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+  ATTEMPT=$((ATTEMPT + 1))
+  
+  if mise run test:unit; then
+    echo "✅ Tests passed"
+    exit 0
+  fi
+  
+  if [ $ATTEMPT -lt $MAX_ATTEMPTS ]; then
+    echo "⚠️ Attempting auto-fix..."
+    bash scripts/auto-fix.sh tests
+  fi
+done
+
+echo "❌ Tests still failing"
+exit 1
+"""
+```
+
+### Git Hooks con Recovery
+
+```toml
+[hooks.pre-commit]
+run = """
+#!/usr/bin/env bash
+set -e
+
+# Lint con auto-fix
+if ! mise run lint; then
+  echo "⚠️ Lint failed, attempting auto-fix..."
+  bash scripts/auto-fix.sh lint && git add -u
+fi
+
+# Tests con retry
+ATTEMPT=0
+while [ $ATTEMPT -lt 2 ]; do
+  if mise run test:changed; then
+    break
+  fi
+  ATTEMPT=$((ATTEMPT + 1))
+  [ $ATTEMPT -lt 2 ] && bash scripts/auto-fix.sh tests
+done
+
+echo "✅ Pre-commit checks passed!"
+"""
+```
+
+---
+
+## 🎯 Progressive Disclosure (Setup en Fases)
+
+### Filosofía: No Abrumar al Inicio
+
+**Antes:**
+```
+Día 1: Instalar 15 herramientas → 3 horas ❌
+```
+
+**Ahora:**
+```
+MVP (15 min):  mise + SQLite → Código funcionando ✅
+Alpha (1h):    PostgreSQL + CI
+Beta (2-3h):   Monitoring + Deploy
+```
+
+### Fase 1: MVP (5-15 minutos)
+
+```bash
+#!/bin/bash
+# scripts/setup-mvp.sh
+
+echo "🚀 Setting up MVP (5-15 minutes)"
+
+# Instalar Mise
+if ! command -v mise &> /dev/null; then
+  curl https://mise.run | sh
+fi
+
+# Instalar herramientas
+mise install
+
+# Crear .env mínimo (SQLite, sin Docker)
+cat > .env << EOF
+DATABASE_URL=sqlite:///dev.db
+NODE_ENV=development
+EOF
+
+# Setup git hooks
+mise hook-env
+
+echo "✅ MVP Setup Complete!"
+echo "🎉 Ready to code! Run: mise run dev"
+```
+
+### Fase 2: Alpha (1 hora)
+
+```bash
+#!/bin/bash
+# scripts/setup-alpha.sh
+
+echo "🚀 Upgrading to Alpha (1 hour)"
+
+# Docker Compose
+cat > docker-compose.yml << EOF
+version: '3.8'
+services:
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: mydb
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5432:5432"
+EOF
+
+# Iniciar PostgreSQL
+mise run docker:up
+
+# Actualizar .env
+sed -i 's|sqlite|postgresql://postgres:postgres@localhost:5432/mydb|' .env
+
+# Migraciones
+mise run db:migrate
+
+# Setup CI básico
+mkdir -p .github/workflows
+# Copiar CI template...
+
+echo "✅ Alpha Complete!"
+```
+
+### Fase 3: Beta (2-3 horas)
+
+```bash
+#!/bin/bash  
+# scripts/setup-beta.sh
+
+echo "🚀 Upgrading to Beta (2-3 hours)"
+
+# Monitoring, deployment, secrets
+echo "Choose deployment platform:"
+echo "  1) Railway"
+echo "  2) Koyeb"
+echo "  3) Coolify"
+read -p "Choice: " choice
+
+# Setup según elección...
+
+echo "✅ Beta Complete - Production ready!"
+```
+
+### Mise Tasks para Fases
+
+```toml
+[tasks."setup:mvp"]
+description = "Phase 1: MVP (5-15 min)"
+run = "bash scripts/setup-mvp.sh"
+
+[tasks."setup:alpha"]  
+description = "Phase 2: Alpha (1 hour)"
+run = "bash scripts/setup-alpha.sh"
+
+[tasks."setup:beta"]
+description = "Phase 3: Beta (2-3 hours)"
+run = "bash scripts/setup-beta.sh"
+
+[tasks.setup]
+description = "Interactive setup wizard"
+run = """
+echo "Choose phase:"
+echo "  1) MVP    - Quick start (15 min)"
+echo "  2) Alpha  - Full dev (1 hour)"
+echo "  3) Beta   - Production (2-3 hours)"
+read -p "Choice [1-3]: " choice
+
+case $choice in
+  1) mise run setup:mvp ;;
+  2) mise run setup:alpha ;;
+  3) mise run setup:beta ;;
+esac
+"""
+```
+
+---
+
+## 📊 Context Script (para Claude Code)
+
+### Problema: Context Window Pollution
+
+**Sin Context Script:**
+```
+❌ Claude lee 50+ archivos → 10,000 tokens
+❌ Lento y costoso
+```
+
+**Con Context Script:**
+```
+✅ 1 comando → Estado completo → < 500 tokens
+✅ JSON parseable
+```
+
+### Implementación
+
+```bash
+#!/bin/bash
+# scripts/agent-context.sh
+
+cat << EOF
+{
+  "timestamp": "$(date -Iseconds)",
+  "git": {
+    "branch": "$(git branch --show-current)",
+    "status": "$(git status -s | wc -l) files changed",
+    "last_commit": "$(git log -1 --pretty=format:'%h - %s')"
+  },
+  "tools": {
+    "node": "$(mise current node 2>/dev/null || echo 'N/A')",
+    "python": "$(mise current python 2>/dev/null || echo 'N/A')",
+    "go": "$(mise current go 2>/dev/null || echo 'N/A')"
+  },
+  "tests": {
+    "status": "$(mise run test:unit >/dev/null 2>&1 && echo 'passing' || echo 'failing')",
+    "coverage": "$(grep -oP '\d+%' coverage.txt 2>/dev/null || echo 'unknown')"
+  },
+  "database": {
+    "migrations": $(ls migrations/*.sql 2>/dev/null | wc -l),
+    "pending": $(mise run db:status 2>/dev/null | grep -c 'pending' || echo 0),
+    "connection": "$(psql "$DATABASE_URL" -c 'SELECT 1' >/dev/null 2>&1 && echo 'ok' || echo 'failed')"
+  },
+  "build": {
+    "lint": "$(mise run lint >/dev/null 2>&1 && echo 'passing' || echo 'failing')",
+    "last_error": "$(tail -n 3 .last-error 2>/dev/null || echo 'none')"
+  },
+  "todos": [
+    $(grep -r "TODO\|FIXME" src/ 2>/dev/null | head -n 5 | awk '{print "\"" $0 "\""}' | paste -sd,)
+  ],
+  "phase": "$([ -f docker-compose.yml ] && echo 'alpha' || echo 'mvp')",
+  "health": {
+    "api_running": $(curl -s http://localhost:8080/health >/dev/null 2>&1 && echo 'true' || echo 'false'),
+    "db_running": $(docker ps | grep -q postgres && echo 'true' || echo 'false')
+  }
+}
+EOF
+```
+
+### Mise Integration
+
+```toml
+[tasks.context]
+description = "Show complete project context (for AI agents)"
+run = "bash scripts/agent-context.sh"
+alias = "ctx"
+
+[tasks."context:watch"]
+description = "Watch context in real-time"
+run = "watch -n 2 'bash scripts/agent-context.sh | jq'"
+```
+
+### Uso en Claude Code
+
+```bash
+# Al inicio de cada turno
+mise run context
+
+# Claude obtiene TODO el estado en < 500 tokens:
+# - Qué rama está activa
+# - Tests passing/failing
+# - Migraciones pendientes
+# - TODOs pendientes
+# - Health checks
+# - Fase del proyecto (mvp/alpha/beta)
+```
+
+---
+
+## 🔄 Atomic Sequential Merges (El Corazón del Agente)
+
+### ⚠️ Aclaración Importante: NO es "1 rama = 1 commit"
+
+```
+❌ MODELO INCORRECTO (lo que NO debes hacer):
+
+feat/01-add-model          → 1 commit → merge
+feat/02-add-migration      → 1 commit → merge  
+feat/03-add-tests          → 1 commit → merge
+
+Problema: Crear una rama nueva por cada commit es una locura
+```
+
+```
+✅ MODELO CORRECTO (Atomic Sequential Merges):
+
+feat/01-database-schema (UNA SOLA RAMA)
+  ├─ commit: "add User model"
+  ├─ commit: "add Post model"  
+  ├─ commit: "add migration script"
+  ├─ commit: "add tests"
+  └─ SQUASH MERGE → develop (4 commits → 1 commit limpio)
+
+feat/02-api-endpoints (siguiente rama)
+  ├─ commit: "add GET /users endpoint"
+  ├─ commit: "add POST /users endpoint"
+  ├─ commit: "add validation middleware"
+  ├─ commit: "add error handling"
+  ├─ commit: "add tests"
+  └─ SQUASH MERGE → develop (5 commits → 1 commit limpio)
+
+Ventaja: 
+✅ Una rama = un paso completo
+✅ Múltiples commits durante desarrollo
+✅ Historia limpia en develop (1 commit por paso)
+```
+
+### El Problema con Stacked PRs para Solo Devs
+
+```