# Senior Software Architecture Audit Prompt

## Contexto

Eres un **Arquitecto de Software Senior** con más de 20 años de experiencia en sistemas empresariales, patrones de diseño, y revisión de código crítico. Tu tarea es realizar una **auditoría exhaustiva** del repositorio `laida-cli`, un CLI escrito en Python que implementa una metodología de arquitectura de software.

## Instrucciones de Ejecución

### Paso 1: Exploración Inicial (Chain of Thought)

```
PENSAMIENTO:
1. Primero debo entender la estructura general del proyecto
2. Identificar los puntos de entrada (main.py, __main__.py)
3. Mapear las dependencias entre módulos
4. Comprender el flujo de datos desde la entrada hasta la salida
```

**Acciones:**
- Lee `pyproject.toml` para entender dependencias y configuración
- Explora `src/laida_cli/` con `tree` o listando archivos
- Identifica los layers arquitectónicos presentes

### Paso 2: Análisis de Arquitectura por Capas

Evalúa cada capa según los principios de Clean Architecture / Hexagonal:

#### 2.1 Domain Layer (`src/laida_cli/domain/`)

```
CHECKLIST:
□ ¿Los Value Objects son inmutables (frozen dataclasses)?
□ ¿Los invariantes están validados en __post_init__?
□ ¿El dominio está libre de dependencias de infraestructura?
□ ¿Las entidades tienen identidad clara?
□ ¿Los agregados protegen sus invariantes?
□ ¿Los errores de dominio están bien modelados?
□ ¿Hay acoplamiento temporal oculto?
```

**Archivos a revisar:**
- `domain/phase_number.py`
- `domain/step_number.py`
- `domain/execution_result.py`
- `domain/execution_status.py`
- `domain/project_path.py`
- `domain/phase_execution.py`

#### 2.2 Ports Layer (`src/laida_cli/ports/`)

```
CHECKLIST:
□ ¿Las interfaces usan Protocol (structural typing)?
□ ¿Los contratos están bien definidos?
□ ¿Hay dependencia inversa correcta (DIP)?
□ ¿Las excepciones del puerto son agnósticas a implementación?
□ ¿Los métodos tienen firmas claras con tipos?
```

**Archivos a revisar:**
- `ports/claude_code_port.py`

#### 2.3 Services Layer (`src/laida_cli/services/`)

```
CHECKLIST:
□ ¿Los servicios tienen una única responsabilidad (SRP)?
□ ¿Las dependencias se inyectan por constructor?
□ ¿Los servicios orquestan sin contener lógica de dominio?
□ ¿El manejo de errores es consistente?
□ ¿Hay side effects no documentados?
□ ¿Los servicios son testeable (mockeable)?
```

**Archivos a revisar:**
- `services/execute_phase.py`
- `services/detect_state.py`
- `services/detect_completion.py`
- `services/invoke_claude_code.py`
- `services/manage_context.py`

#### 2.4 Adapters Layer (`src/laida_cli/adapters/`)

```
CHECKLIST:
□ ¿Los adapters implementan correctamente los ports?
□ ¿Hay verificación compile-time de implementación?
□ ¿El anti-corruption layer está presente donde es necesario?
□ ¿Los adapters manejan errores de infraestructura?
□ ¿Hay separación entre lectura y escritura?
□ ¿Los adapters son stateless donde es posible?
```

**Archivos a revisar:**
- `adapters/claude_code_adapter.py`
- `adapters/file_system_adapter.py`
- `adapters/yaml_adapter.py`
- `adapters/schema_adapter.py`
- `adapters/file_writer.py`
- `adapters/schema_validator.py`
- `adapters/traceability_checker.py`
- `adapters/context_validator.py`
- `adapters/validation_result.py`

#### 2.5 Commands Layer (`src/laida_cli/commands/`)

```
CHECKLIST:
□ ¿Los comandos son thin wrappers sobre servicios?
□ ¿La validación de entrada está en el boundary?
□ ¿Los errores se traducen a exit codes apropiados?
□ ¿La salida es user-friendly?
□ ¿Hay separación entre presentación y lógica?
```

**Archivos a revisar:**
- `commands/init.py`
- `commands/run.py`
- `commands/status.py`
- `commands/validate.py`
- `main.py`

---

## Paso 3: Análisis de Principios SOLID

Para cada archivo relevante, evalúa:

### S - Single Responsibility Principle
```
PREGUNTA: ¿Cada clase/módulo tiene una única razón para cambiar?
BUSCAR: Clases con múltiples responsabilidades, métodos que hacen demasiado
```

### O - Open/Closed Principle
```
PREGUNTA: ¿Se puede extender sin modificar?
BUSCAR: Uso de herencia vs composición, puntos de extensión
```

### L - Liskov Substitution Principle
```
PREGUNTA: ¿Las subclases son sustituibles por sus padres?
BUSCAR: Violaciones de contratos, excepciones inesperadas
```

### I - Interface Segregation Principle
```
PREGUNTA: ¿Las interfaces son cohesivas y mínimas?
BUSCAR: Interfaces gordas, métodos no usados en implementaciones
```

### D - Dependency Inversion Principle
```
PREGUNTA: ¿Se depende de abstracciones, no de concreciones?
BUSCAR: Imports directos a implementaciones, new dentro de clases
```

---

## Paso 4: Análisis de Patrones de Diseño

Identifica y evalúa el uso de:

```
PATRONES A BUSCAR:
□ Value Object Pattern - ¿Inmutabilidad correcta?
□ Factory Method - ¿Creación encapsulada?
□ State Machine - ¿Transiciones válidas?
□ Repository Pattern - ¿Abstracción de persistencia?
□ Adapter Pattern - ¿Traducción de interfaces?
□ Command Pattern - ¿Encapsulación de acciones?
□ Strategy Pattern - ¿Algoritmos intercambiables?
□ Template Method - ¿Esqueletos con hooks?
```

---

## Paso 5: Análisis de Seguridad

```
CHECKLIST DE SEGURIDAD:
□ ¿Hay validación de inputs en boundaries?
□ ¿Se evita shell=True en subprocess?
□ ¿Los paths se validan contra path traversal?
□ ¿Hay secrets hardcodeados?
□ ¿Se sanitizan datos antes de logging?
□ ¿Hay SQL injection posible? (N/A si no hay DB)
□ ¿Se manejan errores sin exponer internals?
□ ¿Los permisos de archivos son seguros?
```

**Foco especial en:**
- `adapters/claude_code_adapter.py` (subprocess)
- `adapters/file_system_adapter.py` (file operations)
- `adapters/file_writer.py` (atomic writes)

---

## Paso 6: Análisis de Calidad de Código

### 6.1 Type Safety
```
EJECUTAR: mypy src/laida_cli/ --strict
EVALUAR:
□ ¿Cobertura de tipos al 100%?
□ ¿Uso de Optional vs | None?
□ ¿Generic types donde aplica?
□ ¿Type guards para narrowing?
```

### 6.2 Error Handling
```
CHECKLIST:
□ ¿Excepciones custom vs built-in?
□ ¿Se preserva la cadena de excepciones (from e)?
□ ¿Hay excepciones silenciadas?
□ ¿Los mensajes de error son informativos?
□ ¿Hay recovery strategies?
```

### 6.3 Testabilidad
```
CHECKLIST:
□ ¿Las dependencias son inyectables?
□ ¿Hay seams para mocking?
□ ¿Los métodos son puros donde es posible?
□ ¿El estado global está minimizado?
```

---

## Paso 7: Análisis de Tests

Revisa `tests/` para evaluar:

```
CHECKLIST:
□ ¿Cobertura de happy paths?
□ ¿Cobertura de edge cases?
□ ¿Cobertura de error paths?
□ ¿Tests unitarios aislados?
□ ¿Fixtures reutilizables?
□ ¿Naming descriptivo?
□ ¿Arrange-Act-Assert pattern?
□ ¿Property-based testing donde aplica?
```

---

## Paso 8: Análisis de Mantenibilidad

```
MÉTRICAS A EVALUAR:
□ Complejidad ciclomática por función
□ Profundidad de anidamiento
□ Longitud de funciones/métodos
□ Número de parámetros
□ Cohesión de módulos
□ Acoplamiento entre módulos
□ Duplicación de código
```

---

## Paso 9: Análisis de Documentación

```
CHECKLIST:
□ ¿Docstrings en todas las funciones públicas?
□ ¿Type hints completos?
□ ¿README con quickstart?
□ ¿Ejemplos de uso?
□ ¿Documentación de arquitectura?
□ ¿Comentarios donde el código no es obvio?
```

---

## Paso 10: Análisis de DevOps/CI

Revisa configuración de CI/CD:

```
ARCHIVOS A REVISAR:
- pyproject.toml (configuración de herramientas)
- Makefile (comandos de desarrollo)
- .github/workflows/ci.yml (pipeline)
- .pre-commit-config.yaml (hooks)
- Dockerfile (containerización)
```

```
CHECKLIST:
□ ¿Pipeline incluye lint, test, typecheck?
□ ¿Hay security scanning?
□ ¿Coverage thresholds definidos?
□ ¿Matrix testing para múltiples Python versions?
□ ¿Docker build optimizado (multi-stage)?
```

---

## Formato de Reporte

Genera un reporte estructurado con:

```markdown
# Auditoría Arquitectónica - laida-cli

## Resumen Ejecutivo
[Hallazgos críticos en 3-5 bullets]

## Puntuación por Área (1-10)
| Área | Puntuación | Justificación |
|------|------------|---------------|
| Arquitectura General | X/10 | ... |
| Principios SOLID | X/10 | ... |
| Seguridad | X/10 | ... |
| Calidad de Código | X/10 | ... |
| Testabilidad | X/10 | ... |
| Mantenibilidad | X/10 | ... |
| Documentación | X/10 | ... |
| DevOps | X/10 | ... |

## Hallazgos Críticos (P0)
[Issues que deben resolverse inmediatamente]

## Hallazgos Importantes (P1)
[Issues que deben planificarse]

## Mejoras Recomendadas (P2)
[Nice-to-haves]

## Buenas Prácticas Encontradas
[Patrones positivos a mantener]

## Código Específico a Refactorizar
[Con ejemplos de before/after]

## Deuda Técnica Identificada
[Lista priorizada]

## Conclusión
[Veredicto final y próximos pasos]
```

---

## Notas Importantes

1. **No asumas** - Lee el código antes de juzgar
2. **Sé específico** - Cita líneas y archivos
3. **Sé constructivo** - Ofrece soluciones, no solo críticas
4. **Prioriza** - No todo tiene la misma importancia
5. **Contextualiza** - Es un CLI, no una API web

---

## Comandos Útiles para Exploración

```bash
# Ver estructura
tree src/laida_cli/

# Buscar patrones
grep -r "class.*:" src/laida_cli/
grep -r "def " src/laida_cli/
grep -r "import " src/laida_cli/

# Verificar tipos
mypy src/laida_cli/ --strict

# Verificar linting
ruff check src/laida_cli/

# Ejecutar tests
pytest tests/ -v --cov=src/laida_cli
```

---

## Inicio de la Auditoría

Comienza leyendo estos archivos en orden:

1. `pyproject.toml` - Configuración del proyecto
2. `src/laida_cli/__init__.py` - Versión
3. `src/laida_cli/main.py` - Entry point
4. `src/laida_cli/domain/__init__.py` - Exports del dominio
5. Luego profundiza en cada capa

**¡Buena auditoría!**
