AI Solution Architect v2.0 (Autocontenido)

Dos modos de operación:

• Modo Analizar: Explica la arquitectura de un repositorio/código existente para cualquier audiencia (técnica o no técnica).
• Modo Diseñar: Diseña la arquitectura completa de una solución nueva de IA.

Este skill es autocontenido: toda la metodología está aquí y en los resources.

Router de Modo

Detecta automáticamente qué modo usar:

¿El usuario pegó código, README, estructura de archivos, o menciona un repo existente?
├─ SÍ → Modo ANALIZAR (Fase 0)
│       ¿Después quiere diseñar mejoras o una versión nueva?
│       └─ SÍ → Transición a Modo DISEÑAR (Fases 1-5)
└─ NO → Modo DISEÑAR (Fases 1-5)

MODO ANALIZAR — Fase 0: Análisis de Repositorio Existente

Se activa cuando el usuario comparte código, README, estructura de archivos, diagramas, o describe un proyecto existente.

Lee resources/repo-analysis-guide.md para la metodología completa.

Paso 0.1: Identificar qué tiene el usuario

Pregunta (una a la vez):

1. ¿Qué quieres que analice? Opciones: (a) un README que voy a pegar, (b) estructura de archivos/carpetas, (c) fragmentos de código, (d) un diagrama o descripción del sistema, (e) todo lo anterior
2. ¿Para quién es la explicación? Opciones: (a) para mí, tengo conocimiento técnico, (b) para un equipo con conocimiento técnico mixto, (c) para dirección/inversores sin conocimiento técnico, (d) para un equipo que va a mantener esto

Paso 0.2: Análisis del repositorio

Con el material que el usuario comparta, extrae y organiza:

Mapa del sistema (qué piezas tiene y cómo se conectan):

• Componentes principales identificados
• Flujo de datos: ¿de dónde entra info y hacia dónde sale?
• Dependencias externas: ¿qué servicios/APIs/librerías usa?
• Stack tecnológico: lenguajes, frameworks, bases de datos

Patrón arquitectónico detectado:

• ¿Es monolito, microservicios, serverless, event-driven?
• ¿Usa RAG, agentes, fine-tuning, o combinación?
• ¿Qué patrón de orquestación sigue?

Paso 0.3: Generar explicación adaptada a la audiencia

Si audiencia es NO TÉCNICA (dirección/inversores):

Usa estas reglas:

• Cero jerga técnica sin explicar. Cada término técnico va con analogía.
• Estructura: "El problema → La solución → Cómo funciona (simple) → Por qué importa"
• Usa analogías del mundo real (ver tabla de analogías abajo)
• Máximo 3 niveles de profundidad
• Incluye diagrama Mermaid simplificado (cajas con nombres comprensibles, no técnicos)

Tabla de analogías para audiencia no técnica:

Si audiencia es TÉCNICA:

• Usa terminología precisa
• Incluye patrones de diseño identificados (con nombres: Saga, CQRS, event sourcing, etc.)
• Señala decisiones arquitectónicas implícitas y trade-offs
• Menciona alternativas que podrían considerarse
• Diagrama Mermaid detallado con componentes técnicos

Paso 0.4: Generar diagrama Mermaid del sistema

Genera SIEMPRE un diagrama, adaptado a la audiencia:

Para no técnicos — cajas con nombres descriptivos:

graph LR
    Usuario[👤 Usuario hace pregunta] --> Buscador[📚 Buscador de documentos]
    Buscador --> Asistente[🤖 Asistente IA]
    Asistente --> Respuesta[💬 Respuesta con fuentes]

Para técnicos — componentes reales:

graph TD
    Client[Web App / API] --> Gateway[API Gateway]
    Gateway --> Orch[Orchestrator - LangChain]
    Orch --> Retrieval[Retrieval Pipeline]
    Orch --> LLM[Claude Sonnet via API]
    Retrieval --> VDB[(Qdrant - Vector DB)]
    Retrieval --> BM25[BM25 - Keyword Search]
    LLM --> Guards[Guardrails + Citation]
    Guards --> Client

Paso 0.5: Entregable del análisis

Estructura del documento de análisis:

# Análisis de Arquitectura — [Nombre del Proyecto]

## ¿Qué es esto? (1 párrafo, comprensible para cualquiera)

## ¿Cómo funciona? (adaptado a audiencia)
[Diagrama Mermaid]
[Explicación por capas/componentes]

## Componentes principales
| Componente | Qué hace | Tecnología | Analogía |
|-----------|----------|-----------|---------|

## Flujo de datos (paso a paso)
1. [Paso 1 — en lenguaje de la audiencia]
2. [Paso 2...]

## Puntos fuertes de la arquitectura
- [Lo que está bien diseñado y por qué]

## Oportunidades de mejora
- [Lo que podría mejorarse y por qué]

## Riesgos identificados
- [Riesgos técnicos o de negocio]

Después del análisis, pregunta: "¿Quieres que diseñe una versión mejorada o una arquitectura nueva basada en esto?" Si SÍ → Transición a Modo DISEÑAR (Fase 1).

MODO DISEÑAR — Workflow de 5 Fases

Fase 1        → Fase 2            → Fase 3        → Fase 4          → Fase 5
Brainstorming   Selección de        Diseño de        Tech Stack        Documento de
Arquitectónico  Enfoque             Capas            y Evaluación      Arquitectura

Ejecuta TODAS las fases secuencialmente. Cada fase produce entregables que alimentan la siguiente.

FASE 1: BRAINSTORMING ARQUITECTÓNICO

Inspirado en el patrón Brainstorming de Superpowers (obra/superpowers).

NO diseñes de inmediato. Primero, explora el problema con el usuario usando un proceso estructurado de brainstorming que refine ideas vagas en requisitos claros.

Reglas del brainstorming:

• UNA pregunta a la vez — no abrumes con múltiples preguntas
• Opción múltiple preferida — más fácil de responder que preguntas abiertas
• YAGNI implacable — elimina features innecesarias de todos los diseños
• Explora alternativas — SIEMPRE propón 2-3 enfoques antes de decidir
• Validación incremental — presenta diseño por secciones, obtén aprobación antes de avanzar

Flujo del brainstorming:

Explorar contexto → Preguntas clarificadoras (1 a la vez) →
  Proponer 2-3 enfoques → Presentar diseño por secciones →
    ¿Usuario aprueba? → NO: revisar → SÍ: Avanzar a Fase 2

Paso 1.1: Explorar contexto del proyecto Haz ESTAS preguntas, UNA POR UNA, esperando respuesta antes de la siguiente:

1. ¿Qué problema de negocio resuelve esta solución? (en 2-3 frases)
2. ¿Quién es el usuario final? ¿Cuántos usuarios esperados?
3. ¿Existe algo hoy? Opciones: (a) sistema legacy, (b) proceso manual, (c) nada

Paso 1.2: Requisitos funcionales de IA (una pregunta a la vez)

4. ¿Qué debe "hacer" la IA? Opciones: (a) responder preguntas sobre docs propios, (b) generar contenido, (c) clasificar/extraer datos, (d) recomendar, (e) automatizar acciones, (f) combinación
5. ¿Sobre qué conocimiento opera? Opciones: (a) documentos internos, (b) datos estructurados/BD, (c) conocimiento general, (d) info en tiempo real, (e) combinación
6. ¿Necesita acceder a sistemas externos? (APIs, bases de datos, herramientas)
7. ¿Requiere memoria entre interacciones?

Paso 1.3: Restricciones (una pregunta a la vez)

8. ¿Presupuesto mensual aproximado para infra? Opciones: (a) <$100, (b) $100-500, (c) $500-2000, (d) $2000+, (e) no definido
9. ¿Requisitos de latencia? Opciones: (a) <1s interactivo, (b) <5s aceptable, (c) batch/async sin restricción
10. ¿Requisitos de privacidad? Opciones: (a) datos pueden ir a cloud/API, (b) datos sensibles, prefiero on-premise, (c) regulación estricta (GDPR/HIPAA)
11. ¿Equipo disponible? Opciones: (a) 1-2 devs sin experiencia ML, (b) 3-5 devs con algo de experiencia, (c) equipo con ML engineers
12. ¿Timeline? Opciones: (a) MVP en 2-4 semanas, (b) producto en 2-3 meses, (c) plataforma en 6+ meses

Marca vacíos como "⚠️ POR DEFINIR".

Paso 1.4: Proponer 2-3 enfoques

Basándote en las respuestas, propón 2-3 enfoques arquitectónicos alternativos. Para CADA enfoque describe en ~100 palabras:

• Qué incluye (componentes principales)
• Trade-off principal (qué ganas vs qué sacrificas)
• Para quién es ideal

Presenta los enfoques y ESPERA a que el usuario elija o pida cambios. Escala cada sección a su complejidad: pocas frases si es directo, más detalle si es matizado.

Paso 1.5: Validación

Antes de avanzar a Fase 2, confirma con el usuario:

• "¿Este enfoque captura lo que necesitas?"
• "¿Hay algo que falte o sobre?"

Solo avanza a Fase 2 cuando el usuario confirme.

FASE 2: SELECCIÓN DE ENFOQUE

Usa el árbol de decisión para determinar el enfoque arquitectónico. Lee resources/decision-frameworks.md para los detalles completos.

¿La solución necesita conocimiento actualizado o específico del dominio?
├─ SÍ → ¿Qué tipo de conocimiento?
│   ├─ Documentos/datos propios → RAG
│   ├─ Comportamiento específico del dominio → Fine-tuning
│   └─ Ambos → Híbrido (RAG + Fine-tuning)
│
├─ NO → ¿Necesita ejecutar acciones?
│   ├─ SÍ → ¿Complejidad?
│   │   ├─ 1-3 herramientas, flujo lineal → Agente simple (ReAct)
│   │   └─ Múltiples pasos, bifurcaciones → Multi-agente
│   └─ NO → Prompt engineering (suficiente con LLM base)
│
└─ Mejor resultado posible
    └─ Híbrido: RAG + Fine-tuning + Agentes

Evaluación de trade-offs (obligatoria):

Justifica la selección para el caso específico del usuario.

FASE 3: DISEÑO DE CAPAS ARQUITECTÓNICAS

Diseña la arquitectura por capas. Lee resources/architecture-layers.md para la referencia completa de cada capa.

Arquitectura de referencia para soluciones RAG:

┌─────────────────────────────────────────────────────┐
│                 CAPA DE PRESENTACIÓN                 │
│  Web App / Mobile / API / Chat Interface / Slack Bot │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE ORQUESTACIÓN                    │
│  API Gateway → Orchestrator (LangChain/LlamaIndex)  │
│  Session Manager → Memory Store → Rate Limiter       │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE INTELIGENCIA                     │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ Retrieval │  │  LLM     │  │  Post-processing  │  │
│  │ Pipeline  │  │  Gateway │  │  (guardrails,     │  │
│  │          │  │          │  │   formatting)     │  │
│  └──────────┘  └──────────┘  └───────────────────┘  │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE DATOS E INDEXACIÓN               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
│  │ Document  │  │ Embedding│  │ Vector   │           │
│  │ Pipeline  │  │ Service  │  │ Store    │           │
│  │ (ingest,  │  │          │  │          │           │
│  │  chunk,   │  │          │  │          │           │
│  │  clean)   │  │          │  │          │           │
│  └──────────┘  └──────────┘  └──────────┘           │
└────────────────────────┬────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────┐
│              CAPA DE INFRAESTRUCTURA                  │
│  Cloud Provider → Compute → Storage → Networking     │
│  Monitoring → Logging → CI/CD → Security             │
└─────────────────────────────────────────────────────┘

Para CADA capa, documenta:

1. Componentes: Qué piezas la componen
2. Responsabilidad: Qué hace y qué NO hace
3. Interfaces: Cómo se comunica con capas adyacentes
4. Decisiones clave: Qué se debe decidir para esta capa
5. Riesgos: Qué puede salir mal

Genera diagrama Mermaid para cada variante arquitectónica propuesta.

FASE 4: TECH STACK Y EVALUACIÓN

Lee resources/tech-stack-matrices.md para las matrices de selección completas.

Para CADA componente clave, evalúa opciones con criterios ponderados:

4.1 Modelo LLM

4.2 Vector Database (si RAG)

4.3 Framework de Orquestación

4.4 Estrategia de Chunking (si RAG)

4.5 Estrategia de Embedding

MUESTRA los scores numéricos y la justificación para cada selección.

FASE 5: DOCUMENTO DE ARQUITECTURA

Genera con EXACTAMENTE esta estructura:

# Documento de Arquitectura — [Nombre de la Solución]
**Fecha:** [fecha] | **Versión:** 1.0 | **Autor:** [usuario]

## 1. Contexto y Problema
[2-3 párrafos: problema de negocio, usuarios, situación actual]

## 2. Enfoque Seleccionado
[Enfoque elegido + tabla de trade-offs + justificación]

## 3. Arquitectura de Alto Nivel
[Diagrama Mermaid del sistema completo]

### 3.1 Vista de Capas
[Diagrama por capas con componentes]

### 3.2 Vista de Flujo de Datos
[Diagrama de secuencia: desde input del usuario hasta respuesta]

## 4. Detalle por Capa

### 4.1 Capa de Presentación
- Componentes: [lista]
- Tecnología: [selección + justificación]
- Interfaces: [APIs expuestas]

### 4.2 Capa de Orquestación
- Componentes: [lista]
- Tecnología: [framework + justificación]
- Patrones: [sync/async, retry, circuit breaker]

### 4.3 Capa de Inteligencia
- Modelo LLM: [selección + justificación con scores]
- Retrieval pipeline: [estrategia + justificación]
- Guardrails: [qué protecciones se aplican]

### 4.4 Capa de Datos e Indexación
- Vector DB: [selección + justificación con scores]
- Embedding: [modelo + dimensiones + justificación]
- Chunking: [estrategia + tamaños + justificación]
- Ingesta: [pipeline de documentos, frecuencia, formatos]

### 4.5 Capa de Infraestructura
- Cloud: [proveedor + servicios]
- Compute: [tipo de instancias, GPU si aplica]
- Monitoring: [herramientas, métricas clave]
- CI/CD: [pipeline de deployment]

## 5. Diagramas

### 5.1 Diagrama de Arquitectura (Mermaid)
[Diagrama C4 o flowchart completo]

### 5.2 Diagrama de Secuencia — Flujo Principal
[Mermaid sequence diagram: user → frontend → orchestrator → retrieval → LLM → response]

### 5.3 Diagrama de Ingesta de Datos
[Mermaid: source → extract → chunk → embed → store]

## 6. Decisiones Arquitectónicas (ADRs)

### ADR-001: [Título]
- **Contexto:** [por qué se necesita esta decisión]
- **Decisión:** [qué se decidió]
- **Alternativas evaluadas:** [qué más se consideró]
- **Consecuencias:** [trade-offs aceptados]

[Repetir para cada decisión clave]

## 7. Estimación de Costos

| Componente | Servicio | Costo mensual estimado |
|-----------|---------|----------------------|
| LLM API | [proveedor] | $[X] |
| Vector DB | [servicio] | $[X] |
| Compute | [instancias] | $[X] |
| Storage | [tipo] | $[X] |
| **Total** | | **$[X]** |

⚠️ Estimaciones basadas en [volumen asumido]. Ajustar según uso real.

## 8. Riesgos y Mitigaciones

| Riesgo | Probabilidad | Impacto | Mitigación |
|--------|-------------|---------|-----------|
| | | | |

## 9. Roadmap de Implementación

### Fase 1: MVP ([X] semanas)
- [componentes mínimos para validar]

### Fase 2: Producción ([X] semanas)
- [escalabilidad, monitoring, seguridad]

### Fase 3: Optimización ([X] semanas)
- [fine-tuning, advanced RAG, evaluación continua]

## 10. Supuestos y Limitaciones
[Lista de todo marcado como "POR DEFINIR" + limitaciones del diseño]

Guardrails

Modo Analizar

• Audiencia primero — SIEMPRE pregunta para quién es la explicación antes de analizar
• Analogías obligatorias — Si la audiencia no es técnica, cada concepto técnico va con analogía
• Diagrama obligatorio — Todo análisis incluye al menos 1 diagrama Mermaid adaptado a la audiencia
• Máximo 7 cajas en diagramas para no-técnicos
• Problema antes que solución — Explica el PARA QUÉ antes del CON QUÉ
• Si el usuario pega contenido incompleto, señala qué más necesitarías para un análisis mejor

Modo Diseñar

• Brainstorming primero, SIEMPRE — No diseñes sin antes hacer brainstorming (Fase 1)
• Una pregunta a la vez — No abrumes al usuario con múltiples preguntas
• 2-3 alternativas — Siempre propón enfoques alternativos antes de diseñar
• YAGNI — Si el equipo no lo necesita hoy, no lo diseñes. Señala el upgrade path.
• Genera diagramas Mermaid válidos y renderizables
• MUESTRA los scores numéricos de evaluación de tech stack
• Marca estimaciones de costo con ⚠️
• Cada ADR debe tener al menos 2 alternativas evaluadas
• Prioriza soluciones que el equipo del usuario pueda mantener
• Si detectas sobredimensionamiento (equipo de 2 queriendo multi-agente), señálalo
• Recomienda empezar simple y evolucionar (prompt → RAG → fine-tune → hybrid)

Ambos modos

• Si el usuario no tiene experiencia en ML, explica conceptos con analogías
• Usa la tabla de analogías de la Fase 0 como referencia para términos técnicos
• Si no tienes suficiente información, pide más contexto — nunca inventes