@damenor/agent-docs 0.1.0

package/templates/modules/agents/.agents/skills/doc-write/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: doc-write
+description: >
+  Escribe documentación siguiendo las convenciones Diátaxis + ADR + CONTEXT.
+  Clasifica contenido por tipo antes de escribir, genera ADRs cuando aplica,
+  y mantiene CONTEXT.md actualizado. Todo el contenido en español con términos
+  técnicos en inglés.
+  TRIGGER: Cuando el usuario dice "escribir doc", "documentar X", "crear ADR",
+  "actualizar CONTEXT", "nueva documentación", o se necesita crear/actualizar
+  cualquier archivo de documentación.
+license: Apache-2.0
+metadata:
+  author: damenordev
+  version: "1.0"
+---
+
+# doc-write
+
+## Cuándo Usar
+
+- **Crear documentación nueva**: Cualquier archivo de doc que se necesite generar
+- **Actualizar documentación existente**: Modificar docs que están desactualizados
+- **Escribir ADRs**: Documentar decisiones arquitectónicas significativas
+- **Actualizar CONTEXT.md**: Agregar términos del dominio que surgieron
+- **Actualizar docs/README.md**: Reflejar cambios en el mapa de documentación
+- **Post-feature**: Después de implementar una feature que necesita documentación
+
+## Patrones Críticos
+
+### REGLA #1: Clasificar por Diátaxis ANTES de escribir
+
+Siempre determinar el tipo ANTES de empezar a escribir:
+
+```
+1. ¿Qué necesita el lector?
+   ├── Aprender algo nuevo → Tutorial
+   ├── Resolver un problema → How-to
+   ├── Consultar información → Referencia
+   └── Entender el porqué → Explicación
+
+2. ¿Es una decisión arquitectónica? → ADR (revisar criterios)
+
+3. ¿Es un término del dominio? → CONTEXT.md
+```
+
+### REGLA #2: ADRs — Solo cuando los 3 criterios se cumplen
+
+Un ADR se escribe SOLO cuando TODAS estas condiciones son verdaderas:
+
+1. **Difícil de revertir**: Cambiar esta decisión tendría costo alto (tiempo, dinero, datos)
+2. **Sorprendente**: Un recién llegado no esperaría esta decisión o necesitaría contexto
+3. **Trade-off real**: Hay alternativas válidas con pros/cons genuinos
+
+**Si falla cualquier criterio, NO es un ADR.**
+
+Ver [ADR Format](references/adr-format.md) para detalles completos.
+
+### REGLA #3: CONTEXT.md — Agregar términos cuando emergen
+
+- Agregar términos nuevos cuando aparecen en código o conversaciones
+- Marcar términos ambiguos con `⚠️ AMBIGUO`
+- Mostrar relaciones entre términos (`→`, `←→`, `parte-de`)
+- No repetir lo que ya está en referencia — solo términos del dominio
+
+### REGLA #4: Actualizar docs/README.md al agregar archivos
+
+El mapa de documentación siempre debe reflejar la realidad:
+- Agregar nuevas entradas cuando se crean archivos
+- Marcar como obsoletas las entradas de archivos eliminados
+- Actualizar descripciones si el contenido cambió significativamente
+
+### REGLA #5: Frontmatter YAML obligatorio
+
+```yaml
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active | draft | stub | deprecated
+type: tutorial | how-to | reference | explanation | adr | design | product
+tags: [tag1, tag2, tag3]
+---
+```
+
+Sin `owner`. Siempre incluir `updated` al modificar.
+
+### REGLA #6: Audiencia DUAL — humanos Y agentes IA
+
+Escribir para:
+- **Humanos**: Claridad, ejemplos, flujo lógico
+- **Agentes IA**: Estructura consistente, términos definidos en CONTEXT.md, referencias cruzadas claras
+
+### REGLA #7: Contenido en español, términos técnicos en inglés
+
+```
+✅ "Para configurar el middleware de autenticación..."
+✅ "El endpoint /api/users retorna un array de objetos..."
+✅ "El componente Button acepta la prop `variant`..."
+```
+
+### REGLA #8: NUNCA crear contenido placeholder/TODO
+
+```
+❌ MAL: "TODO: agregar ejemplos" — mejor NO crear el archivo
+❌ MAL: "Contenido pendiente de redacción" — mejor NO crear el archivo
+✅ BIEN: Escribir contenido real y completo, o no crear el archivo
+```
+
+## Guías por Tipo
+
+### Tutorial
+
+**Orientación**: Aprendizaje — el usuario aprende haciendo
+
+**Estructura**:
+```markdown
+---
+created: "..."
+status: active
+type: tutorial
+tags: [...]
+---
+
+# [Título descriptivo del objetivo de aprendizaje]
+
+## Qué vas a construir
+[Descripción del resultado final — 2-3 líneas]
+
+## Prerequisitos
+[Lista concreta de lo que se necesita antes de empezar]
+
+## Paso 1: [Acción concreta]
+[Instrucciones + código]
+### ✅ Verificación
+[Cómo confirmar que el paso funcionó]
+
+## Paso 2: [Acción concreta]
+...
+
+## Resumen
+[Qué se aprendió, qué sigue]
+```
+
+**Tono**: Didáctico, paciente. Un concepto a la vez. Verificar comprensión en cada paso.
+
+**Longitud**: 500-2000 palabras. Si es más largo, dividir en tutoriales secuenciales.
+
+**No incluir**: Explicaciones profundas del porqué (eso es explicación), referenciar otros docs.
+
+### How-to (Guía práctica)
+
+**Orientación**: Resolver un problema — el usuario ya tiene conocimiento previo
+
+**Estructura**:
+```markdown
+---
+created: "..."
+status: active
+type: how-to
+tags: [...]
+---
+
+# Cómo [resolver problema específico]
+
+## Cuándo usar esto
+[1-2 líneas describiendo el escenario]
+
+## Pasos
+1. [Acción directa con código]
+2. [Acción directa con código]
+...
+
+## Resultado esperado
+[Qué debería verse/funcionar al final]
+```
+
+**Tono**: Directo, sin rodeos. Asume que el lector conoce el sistema. No explicar conceptos básicos.
+
+**Cuándo dividir**: Si tiene más de 10 pasos o cubre más de un problema, dividir en múltiples how-tos.
+
+### Referencia
+
+**Orientación**: Información factual — el usuario busca un dato específico
+
+**Estructura**:
+```markdown
+---
+created: "..."
+status: active
+type: reference
+tags: [...]
+---
+
+# [Nombre de la API/sistema/interfaz]
+
+## [Sección principal — endpoints, métodos, props, etc.]
+
+| Nombre | Tipo | Descripción | Default |
+|--------|------|-------------|---------|
+| ...    | ...  | ...         | ...     |
+
+## Ejemplos
+[Código mínimo por cada caso de uso principal]
+```
+
+**Tono**: Neutral, factual, sin narrativa. Tablas y listas sobre prosa.
+
+**Qué incluir**: TODOS los parámetros, TODOS los valores posibles, TODOS los edge cases.
+
+**Qué NO incluir**: Explicaciones de por qué, tutoriales de uso, narrativa.
+
+### Explicación
+
+**Orientación**: Comprensión — el usuario quiere entender el porqué
+
+**Estructura**:
+```markdown
+---
+created: "..."
+status: active
+type: explanation
+tags: [...]
+---
+
+# [Tema que se explica]
+
+## Contexto
+[Por qué existe esto, qué problema resuelve]
+
+## Cómo funciona
+[Vista general sin entrar en código]
+
+## Alternativas consideradas
+[Qué otras opciones existían y por qué se eligió esta]
+
+## Implicaciones
+[Qué significa esta decisión para el futuro]
+```
+
+**Tono**: Discursivo, analítico. Conectar con ADRs cuando aplique (`docs/adr/001-*.md`).
+
+**Cuándo es necesaria**: Cuando un ADR necesita más contexto del que cabe en el formato mínimo, o cuando un concepto se referencia repetidamente en how-tos y tutoriales.
+
+## Guías de ADRs
+
+### Criterios estrictos (los 3 deben cumplirse)
+
+1. **Difícil de revertir**: El cambio tiene costo alto si se revierte
+2. **Sorprendente**: Alguien nuevo no lo esperaría o preguntaría "¿por qué?"
+3. **Trade-off real**: Hay alternativas genuinas con ventajas y desventajas
+
+### Qué califica como ADR
+
+- Forma de la arquitectura (monolito vs microservicios, layered vs hexagonal)
+- Patrones de integración (sync vs async, REST vs GraphQL vs gRPC)
+- Lock-in tecnológico (base de datos, cloud provider, librería core)
+- Decisiones de borde (qué va dentro vs fuera del servicio)
+- Desviaciones deliberadas (cuando se rompe una convención a propósito)
+- Restricciones invisibles (limitaciones no obvias del stack o del dominio)
+
+### Qué NO califica como ADR
+
+- Elecciones obvias (usar Git, usar testing)
+- Fácil de revertir (renombrar una variable, mover un archivo)
+- Sin alternativas reales (no hay otra opción razonable)
+
+### Formato mínimo del ADR
+
+```markdown
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: proposed | accepted | deprecated | superseded
+type: adr
+tags: [arquitectura, decision]
+---
+
+# ADR-001: [Título breve de la decisión]
+
+[1-3 oraciones explicando la decisión, el porqué, y las alternativas consideradas.
+No más de un párrafo. Si necesita más contexto, crear un explanation/ vinculado.]
+```
+
+**Ejemplo real**:
+
+```markdown
+# ADR-002: Usar PostgreSQL con Prisma ORM
+
+Elegimos PostgreSQL + Prisma como capa de datos porque el proyecto necesita
+relaciones complejas entre entidades y Prisma proporciona type-safety en
+TypeScript. Se consideró MongoDB + Mongoose (rechazado por necesitar joins
+frecuentes) y raw SQL (rechazado por perder type-safety).
+```
+
+Ver [ADR Format](references/adr-format.md) para referencia completa.
+
+## Referencias Cruzadas
+
+Usar wikilinks donde sea útil:
+
+```markdown
+Ver [[CONTEXT]] para definiciones de términos del dominio.
+Relacionado con [[ADR-001-event-sourcing]].
+Para pasos prácticos, ver [[how-to/add-new-endpoint]].
+```
+
+## Proceso de Escritura
+
+```
+1. Identificar QUÉ se necesita documentar
+2. Clasificar por Diátaxis (tutorial/how-to/reference/explanation) o ADR
+3. Verificar que no existe ya un archivo para lo mismo
+4. Escribir con el formato y tono correspondiente al tipo
+5. Agregar frontmatter YAML
+6. Actualizar docs/README.md si es un archivo nuevo
+7. Actualizar docs/CONTEXT.md si hay términos nuevos
+8. Verificar que el contenido es real (no placeholder)
+```
+
+## Comandos
+
+### Verificación pre-escritura
+
+```
+1. ¿Ya existe un archivo para este contenido? → Buscar en docs/README.md
+2. ¿Es el tipo correcto? → Verificar con árbol de decisión Diátaxis
+3. ¿Hay términos del dominio nuevos? → Preparar entrada para CONTEXT.md
+4. ¿Necesita ADR? → Verificar los 3 criterios
+```
+
+### Verificación post-escritura
+
+```
+1. ¿Tiene frontmatter YAML? → status, type, tags, created
+2. ¿Está en la carpeta correcta? → tutorials/, how-to/, reference/, explanation/, docs/adr/
+3. ¿docs/README.md refleja el nuevo archivo? → Actualizar mapa
+4. ¿CONTEXT.md tiene los términos nuevos? → Agregar si aplica
+5. ¿El contenido es real? → Sin TODO, sin placeholder, sin secciones vacías
+```
+
+## Ejemplos Reales por Tipo
+
+### Tutorial — Ejemplo de output
+
+```markdown
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: tutorial
+tags: [auth, jwt, onboarding]
+---
+
+# Implementar autenticación JWT
+
+## Qué vas a construir
+Un flujo completo de login/registro con JWT y refresh tokens.
+
+## Prerequisitos
+- Proyecto corriendo localmente (ver [[tutorials/quick-start]])
+- Conocimiento básico de HTTP headers
+
+## Paso 1: Instalar dependencias
+
+```bash
+npm install jsonwebtoken bcryptjs
+npm install -D @types/jsonwebtoken @types/bcryptjs
+```
+
+### ✅ Verificación
+```bash
+npm ls jsonwebtoken
+# → jsonwebtoken@9.0.2
+```
+
+## Paso 2: Crear el servicio de auth
+...[pasos con código real]
+
+## Resumen
+Aprendiste a implementar JWT con refresh tokens.
+Siguiente: [[guides/how-to-protect-routes]]
+```
+
+### How-to — Ejemplo de output
+
+```markdown
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: how-to
+tags: [deployment, vercel, production]
+---
+
+# Cómo hacer deploy a producción
+
+## Cuándo usar esto
+Cuando una feature aprobada en staging está lista para producción.
+
+## Pasos
+1. Crear PR de `develop` a `main`
+2. Esperar que CI pase (lint + test + build)
+3. Merge con squash
+4. Vercel deploya automáticamente desde `main`
+5. Verificar en https://[dominio]
+
+## Rollback
+Si algo falla: Vercel Dashboard → Deployments → "Promote to Production" en el deploy anterior
+```
+
+## Recursos
+
+- [Diátaxis Patterns](references/diataxis-patterns.md) — Patrones detallados por tipo con ejemplos
+- [ADR Format](references/adr-format.md) — Referencia completa del formato ADR
+- Skills relacionados: `doc-scaffold` (inicializar docs), `doc-review` (auditar docs), `doc-maintain` (mantener docs sincronizados), `doc-design` (sistema de diseño)

package/templates/modules/agents/.agents/skills/doc-write/references/adr-format.md

@@ -0,0 +1,194 @@
+---
+created: "2024-01-15"
+status: active
+type: reference
+tags: [adr, decision, arquitectura, formato]
+---
+
+# Formato ADR — Referencia Completa
+
+## Qué es un ADR
+
+Un ADR (Architecture Decision Record) es un documento que captura una decisión arquitectónica importante, el contexto en que se tomó, y sus consecuencias. En este proyecto, los ADRs usan un **formato mínimo**: título + 1-3 oraciones.
+
+## Los 3 Criterios Obligatorios
+
+Un ADR se escribe **SOLO** cuando **TODAS** estas condiciones son verdaderas:
+
+### 1. Difícil de revertir
+
+La decisión tiene un costo alto si se revierte:
+- Tiempo significativo de refactorización
+- Migración de datos compleja o riesgosa
+- Cambio que afecta múltiples equipos o servicios
+- Contrato que compromete recursos a largo plazo
+
+**No es difícil de revertir**: Renombrar una variable, mover un archivo, cambiar un color en CSS
+
+### 2. Sorprendente
+
+Un recién llegado al proyecto no esperaría esta decisión o necesitaría contexto adicional para entenderla:
+- "¿Por qué usan PostgreSQL y no MongoDB para esto?"
+- "¿Por qué la auth está en un servicio separado?"
+- "¿Por qué no usan el framework estándar del equipo?"
+
+**No es sorprendente**: Usar Git, tener tests, usar Tailwind para CSS
+
+### 3. Trade-off real
+
+Hay alternativas válidas con ventajas y desventajas genuinas:
+- Opción A: Más rápido pero menos mantenible
+- Opción B: Más caro pero más confiable
+- Opción C: Estándar del equipo pero no ideal para este caso
+
+**No es trade-off real**: No hay otra opción razonable, o la "alternativa" es claramente inferior
+
+## Plantilla
+
+```markdown
+---
+created: "2024-01-15"
+status: proposed | accepted | deprecated | superseded-by:ADR-NNN
+type: adr
+tags: [tag1, tag2]
+---
+
+# ADR-NNN: [Título breve de la decisión]
+
+[1-3 oraciones explicando:
+- QUÉ se decidió
+- POR QUÉ (la razón principal)
+- QUÉ ALTERNATIVAS se consideraron brevemente]
+
+<!-- Si se necesita más contexto, crear un archivo en explanation/ vinculado -->
+```
+
+## Qué Califica como ADR — Ejemplos
+
+### Sí califica
+
+| Ejemplo | Difícil de revertir | Sorprendente | Trade-off real |
+|---------|---------------------|--------------|----------------|
+| Elegir monolito modular vs microservicios | Alta reescritura | Alguien esperaría microservicios | Escalabilidad vs complejidad |
+| Usar event sourcing para auditoría | Cambio fundamental de arquitectura | No es el enfoque típico | Consistencia vs complejidad |
+| Elegir PostgreSQL sobre MongoDB | Migración de datos + queries | Datos semi-estructurados en relacional | ACID vs flexibilidad |
+| Implementar auth propia vs Auth0 | Cambio afecta todos los usuarios | Auth0 es el default del equipo | Control vs velocidad |
+| Usar GraphQL en vez de REST | Cambio de contrato con clientes | REST es el estándar | Flexibilidad vs simplicidad |
+| Separar servicio de notificaciones | Refactor multi-equipo | Parecería del mismo dominio | Escalabilidad vs latencia |
+| No usar ORM, usar queries raw | Requiere reescribir capa de datos | El equipo usa ORM por defecto | Performance vs productividad |
+| Usar CQRS para el módulo de reporting | Cambio en patrón de datos | Reporting directo es más simple | Performance de lectura vs complejidad |
+
+### No califica
+
+| Ejemplo | Por qué no | Criterio que falla |
+|---------|-----------|-------------------|
+| Usar Git para control de versiones | Es el estándar de la industria | No es sorprendente |
+| Agregar ESLint al proyecto | Se puede quitar en 5 minutos | No es difícil de revertir |
+| Usar React para el frontend | Es la elección obvia del equipo | No es sorprendente, no hay trade-off |
+| Nombrar variables en inglés | Es la convención del equipo | No hay trade-off real |
+| Usar dotenv para variables de entorno | Es el estándar, fácil de cambiar | Falla los 3 criterios |
+| Agregar prettier | Se quita con un commit | No es difícil de revertir |
+
+## Convención de Numeración
+
+```
+ADR-001: Título de la primera decisión
+ADR-002: Título de la segunda decisión
+ADR-003: ...
+```
+
+### Reglas
+
+- **Numeración secuencial**: ADR-001, ADR-002, ADR-003...
+- **Sin gaps**: No saltar números. Si un ADR se descarta, se marca como `status: deprecated` pero el número no se reutiliza
+- **Prefijo en archivo**: `docs/adr/001-titulo-kebab-case.md`
+- **Título único**: El título debe ser descriptivo y no repetirse
+
+### Nombre de archivo
+
+```
+docs/adr/
+├── TEMPLATE.md          # Plantilla reutilizable
+├── 001-monolito-modular.md
+├── 002-postgresql-sobre-mongodb.md
+├── 003-event-sourcing-auditoria.md
+└── 004-auth-propia-vs-auth0.md
+```
+
+## Ciclo de Vida
+
+### Estados de un ADR
+
+```
+proposed → accepted → deprecated
+                  ↘ superseded-by: ADR-NNN
+```
+
+### proposed
+
+El ADR se está discutiendo. Aún no es la decisión final.
+
+```yaml
+status: proposed
+```
+
+### accepted
+
+La decisión fue tomada y se implementa.
+
+```yaml
+status: accepted
+```
+
+### deprecated
+
+La decisión ya no aplica pero se mantiene por historial.
+
+```yaml
+status: deprecated
+```
+
+### superseded
+
+Una decisión posterior reemplaza este ADR.
+
+```yaml
+status: superseded-by:ADR-005
+```
+
+En el ADR que reemplaza:
+```yaml
+status: accepted
+supersedes: ADR-003
+```
+
+## Cuándo Expandir un ADR
+
+Si un ADR necesita más de 3 oraciones, crear un archivo en `explanation/` vinculado:
+
+```markdown
+# ADR-003: Event sourcing para auditoría
+
+Decidimos usar event sourcing para el módulo de auditoría porque los requisitos
+regulatorios exigen un historial inmutable de cambios. Consideramos append-only
+tables pero event sourcing provee mejor trazabilidad. Ver [[explanation/event-sourcing]]
+para contexto detallado.
+```
+
+En `explanation/event-sourcing.md`:
+- Contexto regulatorio completo
+- Alternativas evaluadas con pros/cons detallados
+- Implicaciones para el equipo y la arquitectura
+- Plan de implementación
+
+## Errores Comunes
+
+| Error | Solución |
+|-------|----------|
+| Escribir ADRs para TODO | Solo escribir cuando los 3 criterios se cumplen |
+| ADRs de 2 páginas | Formato mínimo: 1-3 oraciones. Expandir en explanation/ |
+| Numeración inconsistente | Usar secuencial sin gaps |
+| Olvidar actualizar estado | Cambiar `status` cuando la decisión cambia |
+| No vincular con explicaciones | Agregar wikilinks a explanation/ cuando sea necesario |
+| Repetir el mismo ADR | Buscar ADRs existentes antes de crear uno nuevo |
+| ADR sin contexto de alternativas | Siempre mencionar qué alternativas se consideraron |