Skills para IA — Fundamental Playbooks

Copiá el contenido del skill que necesitás.

Creá la carpeta .agents/skills/<nombre>/ en tu proyecto.

Creá el archivo SKILL.md y pegá el contenido.

La estructura .agents/skills/<nombre>/SKILL.md es reconocida por OpenCode, Claude Code, Cursor, Windsurf, Cascade y la mayoría de editores AI. Un solo formato, todas las herramientas.

API Design

# API Design — Fundamental Skill

Skill para diseñar APIs REST predecibles y consistentes. Usar al crear endpoints, definir respuestas, o manejar errores.

---

## Convenciones REST

### Verbos HTTP
- GET — Leer recurso(s). Idempotente. → 200
- POST — Crear recurso. No idempotente. → 201 + Location header
- PUT — Reemplazar completo. Idempotente. → 200
- PATCH — Actualizar parcial. Idempotente. → ...

.agents/skills/api-design/SKILL.md

# API Design — Fundamental Skill

Skill para diseñar APIs REST predecibles y consistentes. Usar al crear endpoints, definir respuestas, o manejar errores.

---

## Convenciones REST

### Verbos HTTP
- GET — Leer recurso(s). Idempotente. → 200
- POST — Crear recurso. No idempotente. → 201 + Location header
- PUT — Reemplazar completo. Idempotente. → 200
- PATCH — Actualizar parcial. Idempotente. → 200
- DELETE — Eliminar. Idempotente. → 204

### Reglas de URLs
- Recursos en plural, inglés: ✅ /api/v1/users ❌ /api/v1/user
- Jerarquía máximo 2 niveles: ✅ /users/42/orders ❌ /users/42/orders/17/items/3
- kebab-case: ✅ /payment-methods ❌ /paymentMethods
- Sin verbos en URL: ✅ DELETE /users/42 ❌ POST /users/42/delete
- Sub-recursos para relaciones: ✅ /users/42/orders ❌ /orders?userId=42
- Query params para filtros: ✅ /orders?status=paid&sort=-createdAt

### Acciones no-CRUD
- ✅ POST /orders/83/cancel (sub-recurso)
- ✅ POST /users/search { "query": {...} } (búsqueda compleja)

---

## Formato de respuesta estándar

### Recurso único
```json
{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-05-14T10:30:00Z"
  }
}
```

### Lista
```json
{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 142,
    "totalPages": 8,
    "requestId": "req_abc123"
  }
}
```

### Error
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "El campo email es requerido.",
    "details": [
      { "field": "email", "reason": "required" }
    ]
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-05-14T10:30:00Z"
  }
}
```

### Reglas del envelope
1. Respuesta exitosa bajo `data`, errores bajo `error`
2. `requestId` en `meta` para tracear requests
3. Listas con `meta` de paginación
4. Errores de validación con array `details`
5. Nunca exponer stack traces en producción
6. Timestamps en ISO 8601 UTC

---

## Status Codes

- 200 OK — GET, PUT, PATCH exitosos
- 201 Created — POST exitoso. Incluir Location header
- 204 No Content — DELETE exitoso
- 400 Bad Request — Request malformado, JSON inválido
- 401 Unauthorized — Token ausente/expirado
- 403 Forbidden — Sin permisos
- 404 Not Found — Recurso no existe
- 409 Conflict — Violación de unicidad
- 422 Unprocessable — Validación de negocio
- 429 Too Many — Rate limit. Incluir Retry-After
- 500 Internal — Error inesperado (nunca a propósito)
- 503 Unavailable — Mantenimiento/dependencia caída

### Códigos de error en body
- VALIDATION_ERROR (400/422): Datos inválidos, con details[]
- AUTHENTICATION_ERROR (401): Token inválido
- AUTHORIZATION_ERROR (403): Sin permisos
- NOT_FOUND (404): Recurso no existe
- CONFLICT (409): Recurso ya existe
- RATE_LIMIT_ERROR (429): Excediste límite
- INTERNAL_ERROR (500): Error del servidor

### Reglas para errores
1. Nunca 200 con `{ "error": "..." }`. El status code debe reflejar el error.
2. `error.message` para usuario final. Stack solo en desarrollo con flag.
3. 5xx: loguear con requestId, timestamp, stack trace.
4. Validaciones: responder con TODOS los campos que fallaron.

---

## Versionado, Paginación y Filtros

### Versionado
- Estrategia: URL prefix `/api/v1/`. Visible, cache-friendly.
- ❌ Header (Accept: application/vnd.api.v1+json) — invisible, rompe CDN
- ❌ Query param (?version=1) — fácil de olvidar
- Breaking change → nueva versión. Campo nuevo → misma versión.
- Deprecar v1 con warning header por 6 meses.

### Paginación
Query params: `?page=1&perPage=20` (máximo 100)
Meta: `{ page, perPage, total, totalPages }`
Usar cursor-based para datasets que cambian frecuentemente.

### Filtros
- `?sort=-createdAt` (prefijo - para descendente)
- `?status=active` (igualdad exacta)
- `?q=fundamental` (búsqueda textual)
- `?from=2026-01-01&to=2026-01-31` (rango de fechas ISO 8601)

CI/CD

# CI/CD — Fundamental Skill

Skill para pipelines de integración y deploy continuo. Usar al configurar GitHub Actions, planificar deploys, o definir QA gates.

---

## Pipeline stages

Orden de ejecución. Stages marcados como cruciales bloquean el deploy si fallan.

1. Install: Dependencias con cache. Lockfile. --frozen-lockfile siempre.
2. Lint: Errores de estilo. Falla si hay warnings.
3. Type c...

.agents/skills/cicd/SKILL.md

# CI/CD — Fundamental Skill

Skill para pipelines de integración y deploy continuo. Usar al configurar GitHub Actions, planificar deploys, o definir QA gates.

---

## Pipeline stages

Orden de ejecución. Stages marcados como cruciales bloquean el deploy si fallan.

1. Install: Dependencias con cache. Lockfile. --frozen-lockfile siempre.
2. Lint: Errores de estilo. Falla si hay warnings.
3. Type check: TypeScript strict. No compila = no pasa.
4. Test (CRUCIAL): Unit + integration. Paralelizá. < 5 minutos.
5. Build (CRUCIAL): Artefacto inmutable. Docker image, static bundle.
6. Security scan: Dependency audit + SAST. Bloquea por critical/high.
7. Deploy staging (CRUCIAL): Automático al mergear a main.
8. E2E smoke test (CRUCIAL): Contra staging. Flujos críticos.
9. Deploy production (CRUCIAL): Manual con approval gate.

---

## Entornos

| Entorno | Propósito | Datos | Deploy | Destruir |
|---------|-----------|-------|--------|----------|
| Local | Desarrollo individual | DB local + seeds | Manual (pnpm dev) | Libre |
| Preview | Por PR. Efímero | DB clonada de staging | Automático por PR | Al cerrar PR |
| Staging | Pre-producción | Anonimizada, realista | Automático al merge | Nunca. Se resetea |
| Production | Usuarios reales | Real. Backups c/hora | Manual con approval | Nunca |

### Reglas de entornos
1. Cada entorno tiene sus propias credenciales
2. Staging debe ser idéntico a producción
3. Preview environments por PR son oro
4. Nadie tiene SSH directo a producción
5. Rotá secrets periódicamente

---

## Estrategias de Deploy

### Rolling
Reemplazo de instancias de a una. Sin downtime, riesgo de inconsistencias durante rollout.
Cuándo: APIs stateless.

### Blue-Green
Dos entornos idénticos. Deploy en green, redirigís tráfico. Rollback instantáneo.
Cuándo: Sistemas críticos. Cuesta el doble en infra.

### Canary
Deploy a pequeño % de usuarios. Monitoreás. Aumentás gradualmente.
Cuándo: Cambios de alto riesgo. Necesitás buen monitoreo.

### Feature Flags
Código "dormido". Activás por configuración. Rollback = desactivar el flag.
Cuándo: Features grandes. Reglas: dueño + fecha expiración, remover cuando estable, testear ON y OFF.

---

## QA Gates

Gates que bloquean el merge/deploy:

1. **Lint & Format** (BLOCK): Bloquea si hay errores
2. **Type check** (BLOCK): Cero any sin justificar
3. **Unit tests** (BLOCK): Coverage ≥ 80%
4. **Integration tests** (BLOCK): Contra DB real
5. **Bundle size** (WARN): Alerta si +10%
6. **Security audit** (BLOCK): Bloquea critical/high
7. **Code review** (BLOCK): Mínimo 1 approve, autor no aprueba
8. **Manual approval** (BLOCK): Solo prod. Lead tech o DevOps

Code Review Checklist

# Code Review Checklist — Fundamental Skill

Skill para revisar PRs y escribir código limpio. Usar antes de mergear cualquier PR en ventures de Fundamental.

---

## Checklist de PR (14 ítems)

Puntaje: X/14. Copiar resultado al PR como comentario.

### Nombres
- [ ] ¿Variables y métodos describen su intención sin necesidad de comentario?
  > Si necesitás un comentario para explicar el nombre, el ...

.agents/skills/code-review/SKILL.md

# Code Review Checklist — Fundamental Skill

Skill para revisar PRs y escribir código limpio. Usar antes de mergear cualquier PR en ventures de Fundamental.

---

## Checklist de PR (14 ítems)

Puntaje: X/14. Copiar resultado al PR como comentario.

### Nombres
- [ ] ¿Variables y métodos describen su intención sin necesidad de comentario?
  > Si necesitás un comentario para explicar el nombre, el nombre está mal. $d → $discountRate.
- [ ] ¿Sin abreviaturas ni nombres de una letra (salvo i, j en loops)?
  > $usr, $ord, $val → siempre explícitos. Tu yo de 3 meses te lo agradecerá.
- [ ] ¿Los booleanos son preguntas: isActive, hasPermission, canProcess?
  > Un booleano que no es pregunta obliga a leer el contexto para entender qué significa.

### Funciones
- [ ] ¿Cada función hace una sola cosa?
  > Si el nombre tiene "and", "or" o "also" ya hace dos cosas. Dividir.
- [ ] ¿Las funciones tienen 3 parámetros o menos?
  > Más de 3 parámetros → probablemente necesitás un Value Object o DTO.
- [ ] ¿No hay funciones de más de 20 líneas?
  > No es absoluta, pero funciones largas casi siempre hacen más de una cosa.

### Acoplamiento (Rigidez — dolor principal)
- [ ] ¿Este cambio tocó 3 archivos o menos?
  > Más de 3 archivos para una sola feature = rigidez. El sistema está mal acoplado.
- [ ] ¿Las dependencias apuntan a interfaces, no a clases concretas?
  > new MySQLRepository() en el negocio = rigidez garantizada. Inyectá la interfaz.
- [ ] ¿No hay if/elseif chains que deberían ser polimorfismo?
  > if type=='paypal' / elseif 'stripe' → cada nuevo tipo requiere tocar ese if.
- [ ] ¿Los módulos modificados pueden testearse de forma independiente?
  > Si para testear A necesitás B, C y D, el acoplamiento es demasiado alto.

### Claridad
- [ ] ¿Los comentarios explican el PORQUÉ, no el QUÉ?
  > // Regulación fiscal GT: IGV 12% → OK. // multiplica por 0.12 → el código ya lo dice.
- [ ] ¿No hay números ni strings mágicos sin nombre?
  > 86400 → SECONDS_PER_DAY. 0.12 → TAX_RATE_GT. "admin" → UserRole.ADMIN.

### IA-Ready (Claude Code / OpenCode)
- [ ] ¿Un agente de IA podría entender el dominio solo con los nombres del código?
  > Tu código es el prompt. Nombres vagos = el agente genera código incorrecto.
- [ ] ¿No hay lógica duplicada que un agente podría amplificar?
  > Los agentes repiten los patrones que ven. Duplicación existente → duplicación ×10.

---

## Diagnóstico de diseño (4 síntomas)

### Rigidez (Rigidity) — TU DOLOR PRINCIPAL
Cambiar una cosa obliga a cambiar muchas otras en cascada. Cada feature tarda el doble.
```js
// Cambiar el formato de fecha toca 18 archivos
// porque está hardcodeado en todos lados
```

### Fragilidad (Fragility)
Un cambio rompe partes que no tienen relación lógica con lo que tocaste.
```js
// Arreglás descuentos y
// misteriosamente se rompe el módulo de envíos
```

### Inmovilidad (Immobility)
No podés reusar una parte sin traerte todo lo demás.
```js
// Querés la lógica de descuentos en otro venture
// pero está acoplada a DB + mailer + sesión
```

### Viscosidad (Viscosity)
Hacer el hack es más fácil que hacerlo bien. El diseño te empuja al camino incorrecto.
```js
// Agregar el feature con un if anidado
// es más rápido que respetar el patrón
```

Sprint cada vez más lentos → Rigidez. Bugs en lugares inesperados → Fragilidad. Imposible reusar entre ventures → Inmovilidad. Siempre conviene el atajo → Viscosidad.

---

## Principios SOLID

### S — Single Responsibility
Una clase, una razón para cambiar.
- ❌ UserService { login() save() sendEmail() generateReport() }
- ✅ UserAuthenticator  UserRepository  UserMailer

### O — Open / Closed (CURA RIGIDEZ)
Abierto para extender, cerrado para modificar.
- ❌ if type=='paypal'... elseif 'stripe'... elseif 'crypto'...
- ✅ interface PaymentGateway { charge(Money $amount): Receipt }

### L — Liskov Substitution
Un subtipo reemplaza a su padre sin sorpresas.
- ❌ class Square extends Rectangle { // rompe setWidth() }
- ✅ class Square implements Shape { area(): float }

### I — Interface Segregation
No obligues a implementar métodos que no usás.
- ❌ interface Worker { work() eat() sleep() }  // el robot no duerme
- ✅ interface Workable { work() }  Feedable { eat() }

### D — Dependency Inversion (CURA RIGIDEZ)
Dependé de abstracciones, no de implementaciones.
- ❌ class OrderService { public MySQLRepo $repo; }
- ✅ __construct(OrderRepositoryInterface $repo)

---

## Glosario

- **Rigidez (Rigidity)**: Cambiar una cosa obliga a cambiar muchas otras. Causa: acoplamiento directo.
- **Fragilidad (Fragility)**: Los cambios rompen partes no relacionadas. Causa: dependencias ocultas.
- **Inmovilidad (Immobility)**: No podés reusar código sin traerte todo. Causa: negocio mezclado con infraestructura.
- **Viscosidad (Viscosity)**: El hack es más fácil que hacerlo bien. Causa: el diseño no facilita la vía correcta.
- **Acoplamiento (Coupling)**: Grado en que un módulo conoce los detalles internos de otro. Alto acoplamiento = Rigidez.
- **Cohesión (Cohesion)**: Grado en que las responsabilidades de una clase pertenecen juntas. Alta cohesión = SRP.
- **Polimorfismo (Polymorphism)**: Tratar distintos tipos de forma uniforme. Reemplaza los if/elseif chains.
- **Deuda técnica (Technical debt)**: Costo futuro de las decisiones apresuradas de hoy. Se acumula con intereses.

Database

# Database — Fundamental Skill

Skill para diseño de bases de datos, migraciones, queries eficientes y transacciones. Usar al diseñar schemas, escribir queries, o planificar migraciones.

---

## Schema Design

### Naming conventions
- Tablas en plural, snake_case: ✅ user_orders ❌ UserOrder
- Primary keys: id UUID o bigint: ✅ id UUID DEFAULT gen_random_uuid()
- Foreign keys: tabla_singular_id: ✅ u...

.agents/skills/database/SKILL.md

# Database — Fundamental Skill

Skill para diseño de bases de datos, migraciones, queries eficientes y transacciones. Usar al diseñar schemas, escribir queries, o planificar migraciones.

---

## Schema Design

### Naming conventions
- Tablas en plural, snake_case: ✅ user_orders ❌ UserOrder
- Primary keys: id UUID o bigint: ✅ id UUID DEFAULT gen_random_uuid()
- Foreign keys: tabla_singular_id: ✅ user_id REFERENCES users(id)
- Timestamps en todas las tablas: created_at, updated_at
- Índices: idx_tabla_columna: ✅ CREATE INDEX idx_orders_user_id ON orders(user_id)
- Booleanos: is_ o has_: ✅ is_active ❌ active
- Enum como string con CHECK: ✅ status TEXT CHECK (status IN (...)) ❌ ENUM type

### Tipos de datos
- UUID: Primary keys, external IDs. ❌ IDs autoincrementales
- TEXT/VARCHAR(n): Strings con tamaño predecible
- TIMESTAMPTZ: Siempre. ❌ TIMESTAMP sin zona horaria
- NUMERIC/DECIMAL: Dinero, porcentajes. ❌ FLOAT para dinero
- JSONB: Datos semi-estructurados. ❌ JSON (sin B, no indexable)
- BOOLEAN: Flags binarios. ❌ TINYINT para booleanos

---

## Migraciones

### Reglas de oro
1. Cada migración es un archivo con timestamp. Nunca edites una migración ya aplicada en producción.
2. Forward-only en producción. Para revertir, creá nueva migración que deshaga el cambio.
3. Probá en staging antes de producción. ALTER TABLE sin probar = ruleta rusa.
4. Nunca mezcles cambios de schema con cambios de datos en la misma migración.
5. Incluí seeds para desarrollo local. Levantar el proyecto debe ser un solo comando.
6. Migraciones deben ser reversibles (método down) para desarrollo.

---

## Query Patterns

### N+1 Queries
- Problema: Una query para N registros + N queries más para datos relacionados
- Solución: Eager loading (JOIN o INCLUDE)

### SELECT *
- Problema: Traés todas las columnas, desperdiciás ancho de banda
- Solución: Seleccioná solo las columnas necesarias. Especialmente importante con JSONB/TEXT

### Missing index
- Problema: Full table scan, exponencial con el crecimiento
- Solución: Índices en WHERE, JOIN, ORDER BY. Basado en queries reales, no suposiciones

### Query en loop
- Problema: Query dentro de un for loop
- Solución: WHERE IN con arrays o batch inserts

### Sin paginación
- Problema: SELECT sin LIMIT/OFFSET en tabla grande
- Solución: Siempre paginá. Cursor-based para datasets que cambian frecuentemente

### Índices — reglas
1. Basado en queries reales, monitoreá slow queries
2. Un índice por query frecuente. Demasiados ralentizan escrituras
3. Índices compuestos: el orden importa (a, b) ≠ (b, a)
4. Partial indexes para WHERE fijo
5. EXPLAIN ANALYZE antes de deployar

---

## Transacciones & Locks

### Niveles de isolation
- READ COMMITTED (default PostgreSQL): Suficiente para 90% de casos
- REPEATABLE READ: Útil para reportes que necesitan consistencia
- SERIALIZABLE: Máxima seguridad, mínimo rendimiento

### Reglas de oro
1. Abrí transacciones solo cuando sea necesario
2. Mantené las transacciones cortas. Nada de HTTP/emails dentro
3. Actualizaciones atómicas de múltiples tablas → transacción
4. Deadlocks: orden consistente de updates lo previene
5. En producción: manejá errores de transacción con retry + backoff

Git & PR Conventions

# Git & PR Conventions — Fundamental Skill

Skill para mantener un historial de Git limpio, navegable y automatizable. Usar al crear branches, escribir commits, y abrir PRs.

---

## Nombres de Ramas

### Prefixes estándar
- `feat/` — Nueva funcionalidad. Ej: feat/user-auth
- `fix/` — Corrección de bug. Ej: fix/login-timeout
- `chore/` — Mantenimiento, dependencias. Ej: chore/update-eslint
- `hotf...

.agents/skills/git/SKILL.md

# Git & PR Conventions — Fundamental Skill

Skill para mantener un historial de Git limpio, navegable y automatizable. Usar al crear branches, escribir commits, y abrir PRs.

---

## Nombres de Ramas

### Prefixes estándar
- `feat/` — Nueva funcionalidad. Ej: feat/user-auth
- `fix/` — Corrección de bug. Ej: fix/login-timeout
- `chore/` — Mantenimiento, dependencias. Ej: chore/update-eslint
- `hotfix/` — Fix urgente en producción. Ej: hotfix/payment-crash
- `docs/` — Documentación. Ej: docs/api-auth-endpoints
- `refactor/` — Refactor sin cambio funcional. Ej: refactor/extract-payment-gateway
- `test/` — Agregar o corregir tests. Ej: test/checkout-e2e

### Reglas
- Siempre en minúsculas. ❌ feat/User-Auth → ✅ feat/user-auth
- kebab-case, no snake_case. ❌ fix/payment_timeout → ✅ fix/payment-timeout
- Inglés. ❌ feat/autenticacion-usuarios → ✅ feat/user-authentication
- Máximo 3 palabras descriptivas. ❌ fix/the-login-form-authentication-token-expiry → ✅ fix/auth-token-expiry
- Incluí número de issue si existe. ❌ fix/bug → ✅ fix/payment-duplicate-#142

---

## Conventional Commits

Formato: `type(scope): descripción`

### Tipos
- feat — Nueva feature
- fix — Bug fix
- chore — Mantenimiento, dependencias
- docs — Solo documentación
- refactor — Refactor sin cambio de comportamiento
- test — Agregar o corregir tests
- perf — Mejora de performance
- ci — CI/CD changes
- style — Formato, punto y coma, espacios

### Reglas de oro
- Imperativo presente: "add", no "added" ni "adding"
- Máximo 72 caracteres en la primera línea
- Un commit = un cambio lógico. Si usás "and", son dos commits
- El body explica el PORQUÉ, no lo que ya dice el diff

### Ejemplos
- ✅ feat(auth): add JWT token refresh logic
- ✅ fix(checkout): prevent double charge on network retry
- ✅ perf(api): add Redis cache for product list endpoint (Before: 850ms, After: 45ms)
- ❌ fix bug (no da contexto)
- ❌ WIP (no es un commit, es un grito de auxilio)
- ❌ updated some stuff and fixed things (vago)

---

## PR Description

### Template
```markdown
### ¿Qué cambia?
Resumen en una frase.

### ¿Por qué?
Contexto de negocio o técnico. Link al issue.

### ¿Cómo lo hice?
Decisiones técnicas clave. Alternativas consideradas.

### ¿Cómo probarlo?
Pasos concretos para QA. Comandos, fixtures, URLs de staging.

### Screenshots / Evidencia
Si es UI: antes/después. Si es API: response de curl.

### Riesgos
Qué podría romperse. Migraciones, cambios de schema.
```

### Checklist de PR
- [ ] ¿El título sigue Conventional Commits?
- [ ] ¿El PR tiene una sola responsabilidad?
- [ ] ¿La descripción incluye el PORQUÉ?
- [ ] ¿Hay instrucciones claras para probar?
- [ ] ¿Los commits están limpios (sin WIP, fix typo)?
- [ ] ¿Revertiste cambios de debug?
- [ ] ¿Corren los tests localmente?

---

## Estrategia de Merge

### Squash and merge (RECOMENDADO)
Todos los commits se comprimen en uno. Historial de main lineal y limpio.
- ✅ PRs con muchos WIP. Ramas con ida y vuelta.
- ✅ Fácil revertir. Un commit = un PR.
- ❌ Pierde historial granular.

### Merge commit
Crea un commit de merge. Preserva todo el historial.
- ✅ Ramas longevas con múltiples features significativas.
- ✅ Claro qué commits entraron juntos.
- ❌ Más ruido visual en git log.

### Rebase and merge
Reescribe commits sobre la punta de main. Historial lineal.
- ✅ Commits individuales preservados. Sin burbujas de merge.
- ❌ Reescribe historia. Más trabajo si hay conflictos.

### Árbol de decisión
1. ¿Tu rama tiene más de 2 días? → merge | rebase
2. ¿Alguien más trabaja en esta rama? → merge | rebase
3. ¿Querés historial lineal? → rebase | merge
4. ¿Los commits cuentan una historia útil? → rebase | squash

### Anti-patrones
- ❌ git push --force a main: sobreescribe historial compartido
- ❌ Mergear sin revisar conflictos: merge commit se crea pero código roto
- ❌ git add . && git commit -m "changes": todo sin discriminar
- ❌ Commits directos a main: saltás review, CI, y la red de seguridad

Incident Response

# Incident Response — Fundamental Skill

Skill para manejar incidentes en producción. Usar cuando algo se rompe — seguir esta guía sin improvisar.

---

## Niveles de severidad

### P1 — Crítico 🔴
Sistema caído o unusable. Impacto en ingresos o datos.
- Site completamente caído, pérdida de datos, brecha de seguridad, core inaccesible
- **Respuesta**: Todo el equipo. War room inmediata.
- **SLA**:...

.agents/skills/incident/SKILL.md

# Incident Response — Fundamental Skill

Skill para manejar incidentes en producción. Usar cuando algo se rompe — seguir esta guía sin improvisar.

---

## Niveles de severidad

### P1 — Crítico 🔴
Sistema caído o unusable. Impacto en ingresos o datos.
- Site completamente caído, pérdida de datos, brecha de seguridad, core inaccesible
- **Respuesta**: Todo el equipo. War room inmediata.
- **SLA**: Respuesta en 5 min. Resolución objetivo: 1 hora.

### P2 — Alto 🟠
Funcionalidad importante degradada con workaround.
- Feature lenta/errores intermitentes, página secundaria caída, emails no se envían
- **Respuesta**: Equipo responsable prioriza sobre trabajo planeado.
- **SLA**: Respuesta en 15 min. Resolución objetivo: 4 horas.

### P3 — Medio 🟡
Bug no crítico. No afecta operación.
- Bug visual, feature secundaria con error, problema de performance sin impacto
- **Respuesta**: Se planifica en sprint actual o siguiente.
- **SLA**: Respuesta en 1 hora. Resolución: próximo release.

---

## Primeros 15 minutos

**00:00** — Detectás el incidente
- No entres en pánico. Anotá hora exacta. Copiá mensaje textual de alerta/usuario.

**00:01** — Confirmá que es real
- Reproducí desde otra sesión. ¿Una persona o generalizado? ¿Deploy reciente (< 2h)?

**00:03** — Abrí canal de comunicación
- #alerts: "INCIDENT: [descripción breve]. Investigando. Actualizaré cada 10 min."
- Si P1, iniciá call de voz. Asigná rol de comunicador.

**00:05** — Diagnóstico inicial
- Dashboard de monitoreo: errores, latencia, throughput.
- Logs recientes filtrando ERROR. Si hay deploy reciente, es el sospechoso #1.
- Alcance: ¿todos los usuarios? ¿una región? ¿un endpoint?

**00:10** — Decidir: rollback o fix forward
- Si deploy reciente → rollback inmediato. No debuguees.
- Sin deploy → investigar causa raíz: ¿pico de tráfico? ¿dependencia caída? ¿DB lenta?
- Documentá hipótesis en el thread.

**00:15** — Actualizá al equipo
- "UPDATE [15 min]: Esto sabemos, esto hacemos, este es el ETA."
- Sin avance → escalá. Mejor pedir ayuda a los 15 min que a las 2 horas.
- P1 sin resolución → notificá liderazgo.

---

## Templates de comunicación

### Inicio (#alerts)
```
🚨 INCIDENT: [Título]
Severidad: P1 / P2 / P3
Scope: [% usuarios / endpoint / región]
Inicio: [HH:MM UTC]
Estado: Investigando
Actualizaré cada 10 minutos. No deploy hasta nuevo aviso.
```

### Update (#alerts, cada 10-15 min)
```
📡 UPDATE [HH:MM UTC] — +10 min
Lo que sabemos: [hallazgos]
Lo que hacemos: [acción actual]
Próximo paso: [siguiente acción]
ETA: [si se conoce]
```

### Resolución (#alerts)
```
✅ RESUELTO [HH:MM UTC] — [duración]
Causa: [una frase]
Qué hicimos: [acción concreta]
Impacto: [usuarios, datos, duración]
Postmortem: [link]
```

---

## Postmortem

### Template
1. **Resumen**: Qué pasó, a quién afectó, cuánto duró (2-3 frases)
2. **Timeline (UTC)**: Tabla hora/evento/acción. Incluí decisiones incorrectas.
3. **Causa raíz**: Los 5 porqués. No te quedes en el síntoma.
4. **Qué salió bien**: Alerta temprana, rollback rápido, comunicación clara.
5. **Qué salió mal**: Sin culpables. "El alerta llegó 8 min tarde."
6. **Action items**: Concretos con responsable y fecha.
7. **¿Cómo evitar que vuelva a pasar?**: Detección más rápida, mejor respuesta, menor blast radius.

---

## Rollback

1. Identificar último deploy bueno: `git log --oneline -10`
2. Ejecutar: `git revert <commit-id>` o redeploy del workflow anterior
3. Verificar: `curl health endpoint`, revisar dashboard de errores
4. Si no resuelve: no es código → infra/dependencia externa/datos. Revisar DB, gateway de pago, etc.
5. Mitigación sin rollback: feature flags, rate limiting, failover, degradación elegante, escalado manual

---

## Lecciones
1. 90% de incidentes vienen de un deploy. Si deployaste hace < 2h, rollback primero.
2. Nunca debuguees en producción. Rollback → reproducí en staging → arreglá → redeployá.
3. La comunicación salva más vidas que el código.
4. El postmortem no busca culpables. Busca que no pase dos veces.
5. Practicá rollback en frío. La primera vez no puede ser durante un P1.

Onboarding Dev

# Onboarding Dev — Fundamental Skill

Skill para integrar nuevos developers al studio y sus ventures. Entregar al nuevo dev el día 1.

---

## Setup del entorno

### Prerrequisitos
- Node.js ≥ 20 LTS → `node --version`
- Git ≥ 2.40 → `git --version`
- Docker ≥ 24 → `docker --version`
- PNPM ≥ 9 → `pnpm --version`
- VS Code (última stable)
- GitHub CLI ≥ 2.40 → `gh --version`

### Pasos
1. Clonar r...

.agents/skills/onboarding/SKILL.md

# Onboarding Dev — Fundamental Skill

Skill para integrar nuevos developers al studio y sus ventures. Entregar al nuevo dev el día 1.

---

## Setup del entorno

### Prerrequisitos
- Node.js ≥ 20 LTS → `node --version`
- Git ≥ 2.40 → `git --version`
- Docker ≥ 24 → `docker --version`
- PNPM ≥ 9 → `pnpm --version`
- VS Code (última stable)
- GitHub CLI ≥ 2.40 → `gh --version`

### Pasos
1. Clonar repos: `git clone git@github.com:fundamental-lat/api.git`
2. Instalar dependencias: `pnpm install`
3. Configurar .env: `cp .env.example .env` (pedir .env de desarrollo al lead)
4. Levantar servicios: `docker compose up -d` → `pnpm dev` (API :3000, Web :5173)
5. Correr migrations y seeds: `pnpm db:migrate && pnpm db:seed`

### Verificación
- API responde en localhost:3000/health → 200 OK
- Frontend carga sin errores en consola
- `pnpm test` → todos verdes
- `pnpm lint` → 0 errors, 0 warnings

---

## Arquitectura del sistema

- **Frontend**: Astro + React. SSG con islas interactivas.
- **API**: Node.js + Fastify. REST /api/v1. JWT auth. Zod validation. Patrón repository.
- **Database**: PostgreSQL 16. Migrations con Drizzle ORM. Nunca SQL raw.
- **Cache**: Redis. Session store y cache de queries. TTLs por tipo de dato.
- **Queue**: BullMQ + Redis. Jobs asíncronos: emails, webhooks. Retry con backoff.
- **Infra**: Docker + Fly.io. CI/CD con GitHub Actions.

### Decisiones clave
- Fastify sobre Express: más rápido, schema validation nativo, mejor TypeScript
- Astro sobre Next.js: 0KB JS por defecto, ideal para contenido estático
- Drizzle sobre Prisma: más liviano, migraciones SQL legibles
- PNPM sobre NPM: instalación más rápida, node_modules estricto

---

## Primer PR — paso a paso

1. Agarrá un ticket con label `good first issue`
2. Creá branch: `git checkout -b feat/mi-primer-feature`
3. Escribí código (empezá por tests si aplica)
4. `pnpm test && pnpm lint` — arreglá antes de pushear
5. Commiteá con Conventional Commits: `git add -p`
6. Abrí PR con template completo
7. Respondé al review — cada comentario es aprendizaje
8. Squash and merge (default)
9. Verificá en staging, cerrá el issue

### Errores comunes
- ❌ Pushear sin correr tests → ✅ `pnpm test` siempre antes
- ❌ PR con 40 archivos y 3 features → ✅ dividir en PRs chicos
- ❌ No leer .env.example completo → ✅ leerlo entero
- ❌ Commitear node_modules o .env → ✅ revisar .gitignore
- ❌ 3 días sin pushear ni preguntar → ✅ push de WIP al final del día

---

## People & Links

### A quién preguntar qué
- Tech Lead: Arquitectura, decisiones técnicas, code review bloqueante
- Frontend Lead: Componentes, diseño, accesibilidad, performance
- Backend Lead: Endpoints, DB, queues, workers
- DevOps: CI/CD, staging, Docker, secrets, dominios
- Product Owner: Requerimientos, prioridad, criterios de aceptación
- Design: Figma, componentes de diseño, flujos de usuario
- QA: Casos de prueba, datos de test, bugs en staging

### Canales
- #dev (Slack): Dudas técnicas, código, bugs, PRs
- #general (Slack): Anuncios, demos, planning
- #alerts (Slack): Incidentes en producción
- Daily 9:30 AM (Google Meet): Qué hice, qué voy a hacer, qué me bloquea
- Sprint Planning: Lunes cada 2 semanas
- Retro: Viernes fin de sprint

Security

# Security — Fundamental Skill

Skill para prácticas de seguridad en ventures de Fundamental. Usar al implementar auth, manejar secrets, revisar dependencias, o escribir código que procesa input de usuario.

---

## Auth Patterns

### JWT (JSON Web Token)
Stateless. Token contiene claims. Ideal para APIs.
- ✅ Access token 15 min. Refresh token 7 días. Rotá secret al detectar uso malicioso
- ❌ Nunc...

.agents/skills/security/SKILL.md

# Security — Fundamental Skill

Skill para prácticas de seguridad en ventures de Fundamental. Usar al implementar auth, manejar secrets, revisar dependencias, o escribir código que procesa input de usuario.

---

## Auth Patterns

### JWT (JSON Web Token)
Stateless. Token contiene claims. Ideal para APIs.
- ✅ Access token 15 min. Refresh token 7 días. Rotá secret al detectar uso malicioso
- ❌ Nunca guardes información sensible en el payload (no está encriptado)

### OAuth 2.0 / OIDC
Third-party login o service-to-service.
- ✅ Usá provider consolidado (Auth0, Clerk, Firebase Auth)
- ❌ No aceptes tokens de providers fuera de tu allowlist. Validá issuer y audience

### API Keys
Identifican cliente, no usuario. Webhooks, integraciones B2B.
- ✅ Prefijo sk_live_xxx. Guardá solo hash en DB. Mostrá key una sola vez
- ❌ No para autenticar usuarios. No en URLs (quedan en logs)

---

## Secrets — 5 reglas de oro

1. Nunca hardcodees secrets. Si commiteaste uno, rotalo inmediatamente.
2. .env en desarrollo (.gitignore). Vault en producción (1Password, HashiCorp, AWS Secrets Manager)
3. Cada entorno tiene sus propios secrets
4. Rotá secrets periódicamente. 6 meses = bomba de tiempo
5. Si un secret se filtró, asumí compromiso. Rotalo y auditá acceso

---

## OWASP Top 7

1. **Broken Access Control**: Validá permisos en cada endpoint, no solo frontend. Middleware de autorización por rol.
2. **Cryptographic Failures**: HTTPS everywhere. HSTS. bcrypt/argon2 para passwords. AES-256 para datos en reposo.
3. **Injection**: Nunca concatenes strings para SQL. ORMs o prepared statements ($1, $2). Validá y sanitizá todo input.
4. **Insecure Design**: Threat modeling en features nuevas. ¿Qué pasa si un usuario malicioso usa esto?
5. **Security Misconfiguration**: Debug off en prod. CSP, X-Frame-Options, Helmet.js.
6. **Vulnerable Components**: Dependabot/Renovate. Auditá semanalmente. Reemplazá dependencias sin mantenimiento.
7. **Auth Failures**: Rate limiting en /login. MFA para admins. Password: mínimo 12 chars.

---

## Dependencias

1. Bloqueá pipeline si hay vulnerabilidades critical/high
2. Dependabot/Renovate con auto-merge para parches (semver patch)
3. Auditá salud del paquete antes de instalar: ¿mantenimiento activo? ¿contributors?
4. Lockfile commiteado siempre. CI usa --frozen-lockfile
5. SBOM (Software Bill of Materials): sabé exactamente qué dependencias tenés

---

## Código Seguro

### Input validation
1. Nunca confíes en el input del usuario — validá en backend aunque hayas validado en frontend
2. Whitelist, no blacklist — definí qué es válido, no qué es prohibido
3. Escapá output según contexto — HTML entities, parameterized queries, encodeURIComponent
4. Usá librerías de validación — Zod, Joi. No regex a mano
5. Limitá tamaño de input — body parser con límite (1MB para JSON)

### Prácticas
1. **Prepared statements**: Nunca concatenar strings para SQL. $1, $2 para raw SQL.
2. **CORS restrictivo**: Origin específico, no *. Methods solo los usados.
3. **Rate limiting**: /login, /register, /reset-password. Bloqueo progresivo.
4. **Logs sin datos sensibles**: Nunca loguees passwords, tokens, datos de tarjeta.
5. **Headers de seguridad**: CSP, HSTS, X-Content-Type-Options, X-Frame-Options. Helmet.js.
6. **CSRF protection**: Tokens CSRF en formularios. SameSite=Strict/Lax en cookies.

Testing

# Testing — Fundamental Skill

Skill para escribir y mantener tests de calidad en ventures de Fundamental. Usar al escribir código nuevo, refactorizar, o configurar CI.

---

## Tipos de test — Pirámide

### Unitarios
- Scope: Una función o método
- Velocidad: milisegundos
- Confianza: Baja — prueba lógica aislada
- La base. Cada función pública debe tener al menos un test unitario.

### Integraci...

.agents/skills/testing/SKILL.md

# Testing — Fundamental Skill

Skill para escribir y mantener tests de calidad en ventures de Fundamental. Usar al escribir código nuevo, refactorizar, o configurar CI.

---

## Tipos de test — Pirámide

### Unitarios
- Scope: Una función o método
- Velocidad: milisegundos
- Confianza: Baja — prueba lógica aislada
- La base. Cada función pública debe tener al menos un test unitario.

### Integración
- Scope: Dos o más módulos juntos
- Velocidad: ms a segundos
- Confianza: Media — prueba que las piezas encajan
- Verifican código con dependencias reales: DB, API, filesystem. Sin mocks.

### End-to-end
- Scope: Sistema completo
- Velocidad: segundos a minutos
- Confianza: Alta — prueba lo que el usuario ve
- Flujos críticos: login, checkout, onboarding. 5 buenos E2E > 50 frágiles.

### Snapshot
- Scope: Output de un componente
- Velocidad: milisegundos
- Confianza: Baja — detecta cambios no intencionales
- Útiles para UI components y serializers.

### Pirámide
- E2E: Pocos (flujos críticos de negocio)
- Integración: Algunos (contratos entre módulos)
- Unitarios: Muchos (lógica de negocio pura, sin IO)

---

## TDD — Rojo → Verde → Refactor

1. **🔴 Rojo**: Escribí un test que falle. Solo uno. El más chico que pruebe algo útil.
2. **🟢 Verde**: Escribí el mínimo código para que pase. No refactores, no optimices.
3. **🔵 Refactor**: Limpiá, extraé métodos, mejorá nombres. Los tests dan la red de seguridad.

### Reglas
- Nunca escribas código de producción sin un test que falle primero.
- El ciclo debe durar minutos, no horas.
- TDD es diseño, no solo testing. Te obliga a pensar en la interfaz antes que en la implementación.
- Si testear algo es difícil, tu diseño está mal. Acoplamiento alto = tests imposibles.

---

## Buenas prácticas

### Nombres que explican el escenario
- ✅ should_return_422_when_email_is_missing()
- ❌ test_validation_1()

### Estructura AAA: Arrange, Act, Assert
```js
// Arrange
const user = buildUser()
// Act
const result = validate(user)
// Assert
expect(result.error).toBe("email required")
```

### Un concepto por test
- ✅ test("retorna 422 si falta email") / test("retorna 422 si email es inválido")
- ❌ test("validación de email funciona")

### Testeá comportamiento, no implementación
- ✅ expect(service.getTotal(cart)).toBe(150)
- ❌ expect(service.calculateTax).toHaveBeenCalledTimes(1)

### Fixtures compartidas, no herencia
- ✅ beforeEach(() => { user = await createTestUser() })
- ❌ class UserTest extends BaseTest { ... }

### Mocks solo para IO externa
- ✅ mockEmailService.send = jest.fn()
- ❌ mockUserRepository.save = jest.fn() // esto es integración, no unit

---

## Anti-patrones

- ❌ Test que pasa siempre (false positive): forzalo a fallar primero
- ❌ Test flaky: causa #1 = dependencia de tiempo/orden/red. Usá fake timers y seeds determinísticas
- ❌ Test que testea el mock, no el código: si mockeás el 80%, no testeás integración real
- ❌ Cobertura 100% como meta: cuesta el doble que 80% sin agregar el doble de seguridad

---

## CI & Coverage

### Gates en orden
1. Lint (ESLint/Biome) — < 30 segundos
2. Type check (TypeScript) — Cero tolerancia a errores
3. Unit tests (Vitest/Jest) — < 2 minutos
4. Integration tests — Contra DB de prueba (Testcontainers/Docker)
5. Coverage check (c8/istanbul) — Mínimo 80% líneas, 70% branches
6. E2E critical paths (Playwright/Cypress) — Solo flows que no pueden fallar

### Coverage targets
- Líneas: ≥ 80%
- Branches: ≥ 70%
- Funciones: ≥ 85%

Herramientas compatibles

🧠 Claude Code

△ OpenCode

🖱️ Cursor

🪟 Windsurf

🤖 ChatGPT

🔗 Copilot

📋 Aider

🔄 Continue

Todas leen .agents/skills/. Copilot usa .github/copilot-instructions.md. ChatGPT acepta pegado directo en el chat.