@damenor/agent-docs 0.1.1 → 0.4.0

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

@@ -1,386 +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.
+  Writes documentation following Diátaxis + ADR + CONTEXT conventions.
+  Classifies content by type before writing, generates ADRs when applicable,
+  and keeps CONTEXT.md updated. All content in English with technical
+  terms kept in English.
+  TRIGGER: When the user says "write doc", "document X", "create ADR",
+  "update CONTEXT", "new documentation", or any documentation file
+  needs to be created/updated.
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 
 # doc-write
 
-## Cuándo Usar
+## When to Use
 
-- **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
+- **Create new documentation**: Any doc file that needs to be generated
+- **Update existing documentation**: Modify docs that are outdated
+- **Write ADRs**: Document significant architectural decisions
+- **Update CONTEXT.md**: Add domain terms that emerged
+- **Update docs/README.md**: Reflect changes in the documentation map
+- **Post-feature**: After implementing a feature that needs documentation
 
-## Patrones Críticos
+## Critical Patterns
 
-### REGLA #1: Clasificar por Diátaxis ANTES de escribir
+### RULE #1: Classify by Diátaxis BEFORE writing
 
-Siempre determinar el tipo ANTES de empezar a escribir:
+Always determine the type BEFORE starting to write:
 
 ```
-1. ¿Qué necesita el lector?
-   ├── Aprender algo nuevo → Tutorial
-   ├── Resolver un problema → How-to
-   ├── Consultar información → Referencia
-   └── Entender el porqué → Explicación
+1. What does the reader need?
+   ├── Learn something new → Tutorial
+   ├── Solve a problem → How-to
+   ├── Look up information → Reference
+   └── Understand the why → Explanation
 
-2. ¿Es una decisión arquitectónica? → ADR (revisar criterios)
+2. Is it an architectural decision? → ADR (check criteria)
 
-3. ¿Es un término del dominio? → CONTEXT.md
+3. Is it a domain term? → CONTEXT.md
 ```
 
-### REGLA #2: ADRs — Solo cuando los 3 criterios se cumplen
+### RULE #2: ADRs — Only when all 3 criteria are met
 
-Un ADR se escribe SOLO cuando TODAS estas condiciones son verdaderas:
+An ADR is written ONLY when ALL these conditions are true:
 
-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
+1. **Hard to reverse**: Changing this decision would have high cost (time, money, data)
+2. **Surprising**: A newcomer would not expect this decision or would need context
+3. **Real trade-off**: There are valid alternatives with genuine pros/cons
 
-**Si falla cualquier criterio, NO es un ADR.**
+**If any criterion fails, it is NOT an ADR.**
 
-Ver [ADR Format](references/adr-format.md) para detalles completos.
+See [ADR Format](references/adr-format.md) for full details.
 
-### REGLA #3: CONTEXT.md — Agregar términos cuando emergen
+### RULE #3: CONTEXT.md — Add terms when they emerge
 
-- 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
+- Add new terms when they appear in code or conversations
+- Mark ambiguous terms with `⚠️ AMBIGUOUS`
+- Show relationships between terms (`→`, `←→`, `part-of`)
+- Do not repeat what is already in reference — only domain terms
 
-### REGLA #4: Actualizar docs/README.md al agregar archivos
+### RULE #4: Update docs/README.md when adding files
 
-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
+The documentation map must always reflect reality:
 
-### REGLA #5: Frontmatter YAML obligatorio
+- Add new entries when files are created
+- Mark entries of deleted files as obsolete
+- Update descriptions if content changed significantly
+
+### RULE #5: YAML frontmatter required
 
 ```yaml
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+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.
+No `owner`. Always include `updated` when modifying.
 
-### REGLA #6: Audiencia DUAL — humanos Y agentes IA
+### RULE #6: DUAL audience — humans AND AI agents
 
-Escribir para:
-- **Humanos**: Claridad, ejemplos, flujo lógico
-- **Agentes IA**: Estructura consistente, términos definidos en CONTEXT.md, referencias cruzadas claras
+Write for:
 
-### REGLA #7: Contenido en español, términos técnicos en inglés
+- **Humans**: Clarity, examples, logical flow
+- **AI agents**: Consistent structure, terms defined in CONTEXT.md, clear cross-references
+
+### RULE #7: Content in English
 
 ```
-✅ "Para configurar el middleware de autenticación..."
-✅ "El endpoint /api/users retorna un array de objetos..."
-✅ "El componente Button acepta la prop `variant`..."
+✅ "To configure the authentication middleware..."
+✅ "The endpoint /api/users returns an array of objects..."
+✅ "The Button component accepts the `variant` prop..."
 ```
 
-### REGLA #8: NUNCA crear contenido placeholder/TODO
+### RULE #8: NEVER create placeholder/TODO content
 
 ```
-❌ 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
+❌ BAD: "TODO: add examples" — better NOT to create the file
+❌ BAD: "Content pending writing" — better NOT to create the file
+✅ GOOD: Write real and complete content, or do not create the file
 ```
 
-## Guías por Tipo
+## Guides by Type
 
 ### Tutorial
 
-**Orientación**: Aprendizaje — el usuario aprende haciendo
+**Orientation**: Learning — the user learns by doing
+
+**Structure**:
 
-**Estructura**:
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: tutorial
 tags: [...]
 ---
 
-# [Título descriptivo del objetivo de aprendizaje]
+# [Descriptive title of the learning goal]
+
+## What you will build
+
+[Description of the end result — 2-3 lines]
+
+## Prerequisites
+
+[Concrete list of what is needed before starting]
+
+## Step 1: [Concrete action]
 
-## Qué vas a construir
-[Descripción del resultado final — 2-3 líneas]
+[Instructions + code]
 
-## Prerequisitos
-[Lista concreta de lo que se necesita antes de empezar]
+### ✅ Verification
 
-## Paso 1: [Acción concreta]
-[Instrucciones + código]
-### ✅ Verificación
-[Cómo confirmar que el paso funcionó]
+[How to confirm the step worked]
+
+## Step 2: [Concrete action]
 
-## Paso 2: [Acción concreta]
 ...
 
-## Resumen
-[Qué se aprendió, qué sigue]
+## Summary
+
+[What was learned, what's next]
 ```
 
-**Tono**: Didáctico, paciente. Un concepto a la vez. Verificar comprensión en cada paso.
+**Tone**: Didactic, patient. One concept at a time. Verify understanding at each step.
+
+**Length**: 500-2000 words. If longer, split into sequential tutorials.
 
-**Longitud**: 500-2000 palabras. Si es más largo, dividir en tutoriales secuenciales.
+**Do not include**: Deep explanations of why (that is explanation), reference other docs.
 
-**No incluir**: Explicaciones profundas del porqué (eso es explicación), referenciar otros docs.
+### How-to (Practical guide)
 
-### How-to (Guía práctica)
+**Orientation**: Solve a problem — the user already has prior knowledge
 
-**Orientación**: Resolver un problema — el usuario ya tiene conocimiento previo
+**Structure**:
 
-**Estructura**:
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: how-to
 tags: [...]
 ---
 
-# Cómo [resolver problema específico]
+# How to [solve specific problem]
 
-## Cuándo usar esto
-[1-2 líneas describiendo el escenario]
+## When to use this
 
-## Pasos
-1. [Acción directa con código]
-2. [Acción directa con código]
-...
+[1-2 lines describing the scenario]
+
+## Steps
 
-## Resultado esperado
-[Qué debería verse/funcionar al final]
+1. [Direct action with code]
+2. [Direct action with code]
+   ...
+
+## Expected result
+
+[What should be seen/working at the end]
 ```
 
-**Tono**: Directo, sin rodeos. Asume que el lector conoce el sistema. No explicar conceptos básicos.
+**Tone**: Direct, no fluff. Assume the reader knows the system. Do not explain basic concepts.
 
-**Cuándo dividir**: Si tiene más de 10 pasos o cubre más de un problema, dividir en múltiples how-tos.
+**When to split**: If it has more than 10 steps or covers more than one problem, split into multiple how-tos.
 
-### Referencia
+### Reference
 
-**Orientación**: Información factual — el usuario busca un dato específico
+**Orientation**: Factual information — the user looks up a specific piece of data
+
+**Structure**:
 
-**Estructura**:
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: reference
 tags: [...]
 ---
 
-# [Nombre de la API/sistema/interfaz]
+# [Name of the API/system/interface]
+
+## [Main section — endpoints, methods, props, etc.]
 
-## [Sección principal — endpoints, métodos, props, etc.]
+| Name | Type | Description | Default |
+| ---- | ---- | ----------- | ------- |
+| ...  | ...  | ...         | ...     |
 
-| Nombre | Tipo | Descripción | Default |
-|--------|------|-------------|---------|
-| ...    | ...  | ...         | ...     |
+## Examples
 
-## Ejemplos
-[Código mínimo por cada caso de uso principal]
+[Minimal code for each main use case]
 ```
 
-**Tono**: Neutral, factual, sin narrativa. Tablas y listas sobre prosa.
+**Tone**: Neutral, factual, no narrative. Tables and lists over prose.
 
-**Qué incluir**: TODOS los parámetros, TODOS los valores posibles, TODOS los edge cases.
+**What to include**: ALL parameters, ALL possible values, ALL edge cases.
 
-**Qué NO incluir**: Explicaciones de por qué, tutoriales de uso, narrativa.
+**What NOT to include**: Explanations of why, usage tutorials, narrative.
 
-### Explicación
+### Explanation
 
-**Orientación**: Comprensión — el usuario quiere entender el porqué
+**Orientation**: Understanding — the user wants to understand the why
+
+**Structure**:
 
-**Estructura**:
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: explanation
 tags: [...]
 ---
 
-# [Tema que se explica]
+# [Topic being explained]
+
+## Context
+
+[Why this exists, what problem it solves]
+
+## How it works
+
+[Overview without going into code]
 
-## Contexto
-[Por qué existe esto, qué problema resuelve]
+## Alternatives considered
 
-## Cómo funciona
-[Vista general sin entrar en código]
+[What other options existed and why this was chosen]
 
-## Alternativas consideradas
-[Qué otras opciones existían y por qué se eligió esta]
+## Implications
 
-## Implicaciones
-[Qué significa esta decisión para el futuro]
+[What this decision means for the future]
 ```
 
-**Tono**: Discursivo, analítico. Conectar con ADRs cuando aplique (`docs/adr/001-*.md`).
+**Tone**: Discursive, analytical. Connect to ADRs when applicable (`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.
+**When needed**: When an ADR needs more context than fits in the minimal format, or when a concept is referenced repeatedly in how-tos and tutorials.
 
-## Guías de ADRs
+## ADR Guides
 
-### Criterios estrictos (los 3 deben cumplirse)
+### Strict criteria (all 3 must be met)
 
-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
+1. **Hard to reverse**: The change has high cost if reversed
+2. **Surprising**: Someone new wouldn't expect it or would ask "why?"
+3. **Real trade-off**: There are genuine alternatives with advantages and disadvantages
 
-### Qué califica como ADR
+### What qualifies as an 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)
+- Architecture shape (monolith vs microservices, layered vs hexagonal)
+- Integration patterns (sync vs async, REST vs GraphQL vs gRPC)
+- Technology lock-in (database, cloud provider, core library)
+- Boundary decisions (what goes inside vs outside the service)
+- Deliberate deviations (when a convention is broken on purpose)
+- Invisible constraints (non-obvious limitations of the stack or domain)
 
-### Qué NO califica como ADR
+### What does NOT qualify as an 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)
+- Obvious choices (using Git, using testing)
+- Easy to reverse (renaming a variable, moving a file)
+- No real alternatives (no other reasonable option)
 
-### Formato mínimo del ADR
+### Minimal ADR format
 
 ```markdown
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+created: '2026-05-07'
+updated: '2026-05-07'
 status: proposed | accepted | deprecated | superseded
 type: adr
-tags: [arquitectura, decision]
+tags: [architecture, decision]
 ---
 
-# ADR-001: [Título breve de la decisión]
+# ADR-001: [Brief title of the decision]
 
-[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.]
+[1-3 sentences explaining the decision, the why, and the alternatives considered.
+No more than one paragraph. If more context is needed, create a linked explanation/]
 ```
 
-**Ejemplo real**:
+**Real example**:
 
 ```markdown
-# ADR-002: Usar PostgreSQL con Prisma ORM
+# ADR-002: Use PostgreSQL with 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).
+We chose PostgreSQL + Prisma as the data layer because the project needs
+complex relationships between entities and Prisma provides type-safety in
+TypeScript. MongoDB + Mongoose was considered (rejected due to frequent joins
+needed) and raw SQL (rejected due to losing type-safety).
 ```
 
-Ver [ADR Format](references/adr-format.md) para referencia completa.
+See [ADR Format](references/adr-format.md) for complete reference.
 
-## Referencias Cruzadas
+## Cross-References
 
-Usar wikilinks donde sea útil:
+Use wikilinks where helpful:
 
 ```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]].
+See [[CONTEXT]] for domain term definitions.
+Related to [[ADR-001-event-sourcing]].
+For practical steps, see [[how-to/add-new-endpoint]].
 ```
 
-## Proceso de Escritura
+## Writing Process
 
 ```
-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)
+1. Identify WHAT needs to be documented
+2. Classify by Diátaxis (tutorial/how-to/reference/explanation) or ADR
+3. Verify a file for the same content does not already exist
+4. Write with the format and tone corresponding to the type
+5. Add YAML frontmatter
+6. Update docs/README.md if it is a new file
+7. Update docs/CONTEXT.md if there are new terms
+8. Verify the content is real (no placeholders)
 ```
 
-## Comandos
+## Commands
 
-### Verificación pre-escritura
+### Pre-writing verification
 
 ```
-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
+1. Does a file for this content already exist? → Search in docs/README.md
+2. Is the type correct? → Verify with Diátaxis decision tree
+3. Are there new domain terms? → Prepare entry for CONTEXT.md
+4. Does it need an ADR? → Check the 3 criteria
 ```
 
-### Verificación post-escritura
+### Post-writing verification
 
 ```
-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
+1. Does it have YAML frontmatter? → status, type, tags, created
+2. Is it in the correct folder? → tutorials/, how-to/, reference/, explanation/, docs/adr/
+3. Does docs/README.md reflect the new file? → Update map
+4. Does CONTEXT.md have the new terms? → Add if applicable
+5. Is the content real? → No TODO, no placeholder, no empty sections
 ```
 
-## Ejemplos Reales por Tipo
+## Real Examples by Type
 
-### Tutorial — Ejemplo de output
+### Tutorial — Output example
 
-```markdown
+````markdown
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+created: '2026-05-07'
+updated: '2026-05-07'
 status: active
 type: tutorial
 tags: [auth, jwt, onboarding]
 ---
 
-# Implementar autenticación JWT
+# Implement JWT Authentication
+
+## What you will build
+
+A complete login/registration flow with JWT and refresh tokens.
 
-## Qué vas a construir
-Un flujo completo de login/registro con JWT y refresh tokens.
+## Prerequisites
 
-## Prerequisitos
-- Proyecto corriendo localmente (ver [[tutorials/quick-start]])
-- Conocimiento básico de HTTP headers
+- Project running locally (see [[tutorials/quick-start]])
+- Basic knowledge of HTTP headers
 
-## Paso 1: Instalar dependencias
+## Step 1: Install dependencies
 
 ```bash
 npm install jsonwebtoken bcryptjs
 npm install -D @types/jsonwebtoken @types/bcryptjs
 ```
+````
+
+### ✅ Verification
 
-### ✅ Verificación
 ```bash
 npm ls jsonwebtoken
 # → jsonwebtoken@9.0.2
 ```
 
-## Paso 2: Crear el servicio de auth
-...[pasos con código real]
+## Step 2: Create the auth service
 
-## Resumen
-Aprendiste a implementar JWT con refresh tokens.
-Siguiente: [[guides/how-to-protect-routes]]
-```
+...[steps with real code]
 
-### How-to — Ejemplo de output
+## Summary
+
+You learned to implement JWT with refresh tokens.
+Next: [[guides/how-to-protect-routes]]
+
+````
+
+### How-to — Output example
 
 ```markdown
 ---
@@ -391,24 +419,24 @@ type: how-to
 tags: [deployment, vercel, production]
 ---
 
-# Cómo hacer deploy a producción
+# How to deploy to production
 
-## Cuándo usar esto
-Cuando una feature aprobada en staging está lista para producción.
+## When to use this
+When an approved feature in staging is ready for production.
 
-## 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]
+## Steps
+1. Create PR from `develop` to `main`
+2. Wait for CI to pass (lint + test + build)
+3. Squash merge
+4. Vercel auto-deploys from `main`
+5. Verify at https://[domain]
 
 ## Rollback
-Si algo falla: Vercel Dashboard → Deployments → "Promote to Production" en el deploy anterior
-```
+If something fails: Vercel Dashboard → Deployments → "Promote to Production" on the previous deploy
+````
 
-## Recursos
+## Resources
 
-- [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)
+- [Diátaxis Patterns](references/diataxis-patterns.md) — Detailed patterns by type with examples
+- [ADR Format](references/adr-format.md) — Complete ADR format reference
+- Related skills: `doc-scaffold` (initialize docs), `doc-review` (audit docs), `doc-maintain` (keep docs synced), `doc-design` (design system)