@damenor/agent-docs 0.1.1 → 0.4.0

package/templates/modules/agents/.agents/skills/doc-write/references/diataxis-patterns.md

@@ -1,351 +1,372 @@
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: reference
-tags: [diataxis, patrones, documentacion, escritura]
+tags: [diataxis, patterns, documentation, writing]
 ---
 
-# Diátaxis — Patrones Detallados por Tipo
+# Diátaxis — Detailed Patterns by Type
 
-## Patrones de Tutorial
+## Tutorial Patterns
 
-### Estructura canónica
+### Canonical structure
 
 ```markdown
-# [Verbo + objeto del aprendizaje]
+# [Verb + learning object]
 
-## Qué vas a construir
-[Resultado tangible que el lector obtendrá]
+## What you'll build
 
-## Prerequisitos
-[Lista exacta: software, conocimientos, acceso]
+[Tangible result the reader will obtain]
 
-## Paso 1: [Acción concreta en infinitivo]
-[Instrucciones paso a paso]
-[Código completo y ejecutable]
+## Prerequisites
+
+[Exact list: software, knowledge, access]
+
+## Step 1: [Concrete action in infinitive]
+
+[Step by step instructions]
+[Complete and executable code]
 
 ### ✅ Verificación
+
 [Comando o acción para confirmar que funciona]
 
 ## Paso N: ...
 
 ## Resumen
+
 [Qué se aprendió]
 [Próximos pasos sugeridos]
 ```
 
-### Tono
+### Tone
 
-- **Didáctico y paciente**: No asumir conocimiento previo del tema
-- **Un concepto a la vez**: Cada paso introduce UNA cosa nueva
-- **Alentador**: Mostrar progreso visible y frecuentemente
-- **Concreto**: Usar ejemplos específicos, no abstractos
+- **Didactic and patient**: Don't assume prior knowledge of the topic
+- **One concept at a time**: Each step introduces ONE new thing
+- **Encouraging**: Show visible progress frequently
+- **Concrete**: Use specific examples, not abstract ones
 
-### Longitud
+### Length
 
-- **Ideal**: 500-1500 palabras
-- **Máximo**: 2000 palabras — si es más, dividir en tutoriales secuenciales
-- **Mínimo**: 300 palabras — si es menos, probablemente es un how-to
+- **Ideal**: 500-1500 words
+- **Maximum**: 2000 words — if longer, split into sequential tutorials
+- **Minimum**: 300 words — if shorter, it's probably a how-to
 
-### Cuándo escribir un tutorial
+### When to write a tutorial
 
-- Un usuario nuevo necesita aprender una habilidad fundamental
-- Hay un flujo de onboarding que nadie ha documentado
-- Un concepto clave se enseña repetidamente a nuevas personas
+- A new user needs to learn a fundamental skill
+- There's an onboarding flow no one has documented
+- A key concept is taught repeatedly to new people
 
-### Ejemplo concreto
+### Concrete example
 
-```markdown
+````markdown
 ---
-created: "2024-03-10"
+created: '2024-03-10'
 status: active
 type: tutorial
 tags: [onboarding, api, express]
 ---
 
-# Crear tu primer endpoint con Express
+# Create your first endpoint with Express
+
+## What you'll build
 
-## Qué vas a construir
-Un endpoint GET /api/health que responda con el estado del servidor.
+A GET /api/health endpoint that responds with the server status.
 
-## Prerequisitos
-- Node.js 18+ instalado
-- Editor de código
+## Prerequisites
+
+- Node.js 18+ installed
+- Code editor
 - Terminal
 
-## Paso 1: Inicializar el proyecto
+## Step 1: Initialize the project
 
-Crea una carpeta nueva e inicializa el proyecto:
+Create a new folder and initialize the project:
 
-\`\`\`bash
-mkdir mi-api && cd mi-api
+```bash
+mkdir my-api && cd my-api
 npm init -y
 npm install express
-\`\`\`
+```
+````
 
-### ✅ Verificación
-Deberías ver `node_modules/` y `package.json` en la carpeta.
+### ✅ Verification
+
+You should see `node_modules/` and `package.json` in the folder.
 
-## Paso 2: Crear el servidor
+## Step 2: Create the server
 
-Crea `index.js`:
+Create `index.js`:
 
-\`\`\`javascript
-const express = require('express');
-const app = express();
+```javascript
+const express = require('express')
+const app = express()
 
 app.get('/api/health', (req, res) => {
-  res.json({ status: 'ok', timestamp: new Date().toISOString() });
-});
+  res.json({ status: 'ok', timestamp: new Date().toISOString() })
+})
 
 app.listen(3000, () => {
-  console.log('Servidor corriendo en http://localhost:3000');
-});
-\`\`\`
+  console.log('Server running at http://localhost:3000')
+})
+```
 
-### ✅ Verificación
-Ejecuta `node index.js` y abre `http://localhost:3000/api/health` en el navegador.
-Deberías ver `{"status":"ok","timestamp":"..."}`.
+### ✅ Verification
 
-## Resumen
-Aprendiste a crear un servidor Express con un endpoint GET.
-Próximo paso: [[tutorials/add-database]] para conectar una base de datos.
-```
+Run `node index.js` and open `http://localhost:3000/api/health` in your browser.
+You should see `{"status":"ok","timestamp":"..."}`.
+
+## Summary
+
+You learned to create an Express server with a GET endpoint.
+Next step: [[tutorials/add-database]] to connect a database.
+
+````
 
-### Anti-patrones de tutorial
+### Tutorial anti-patterns
 
-| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
+| Anti-pattern | Why it's bad | What to do instead |
 |-------------|----------------|----------------------|
-| Explicar teoría antes de practicar | Aburre al principiante | Explicar MIENTRAS se hace |
-| Saltarse pasos de verificación | El lector se pierde sin saberlo | Verificar después de CADA paso |
-| Asumir conocimiento previo | Frustra al principiante | Listar prerequisitos explícitos |
-| Código incompleto o seudo-código | No se puede ejecutar | Código SIEMPRE completo y ejecutable |
-| Cubrir múltiples temas | Satura al lector | Un tutorial = un tema |
-| Enlaces a docs externas para lo básico | Interrumpe el flujo | Incluir todo lo necesario inline |
+| Explaining theory before practice | Bores the beginner | Explain WHILE doing |
+| Skipping verification steps | The reader gets lost without knowing | Verify after EACH step |
+| Assuming prior knowledge | Frustrates the beginner | List prerequisites explicitly |
+| Incomplete or pseudo-code | Cannot be executed | Code ALWAYS complete and executable |
+| Covering multiple topics | Saturates the reader | One tutorial = one topic |
+| External docs links for basics | Interrupts flow | Include everything inline |
 
 ---
 
-## Patrones de How-to
+## How-to Patterns
 
-### Estructura canónica
+### Canonical structure
 
 ```markdown
-# Cómo [resolver problema específico]
+# How to [solve specific problem]
 
-## Cuándo usar esto
-[1-3 líneas: escenario donde aplica esta guía]
+## When to use this
+[1-3 lines: scenario where this guide applies]
 
-## Pasos
-1. [Acción directa]
-2. [Acción directa]
+## Steps
+1. [Direct action]
+2. [Direct action]
 ...
 
-## Resultado esperado
-[Qué se obtiene al final]
-```
+## Expected result
+[What you get at the end]
+````
 
-### Tono
+### Tone
 
-- **Directo**: Al grano, sin preámbulos
-- **Asume conocimiento**: El lector ya conoce el sistema
-- **Práctico**: Pasos concretos, no explicaciones teóricas
-- **Sin justificación**: No explicar por qué — si el lector pregunta por qué, necesita una explicación, no un how-to
+- **Direct**: Straight to the point, no preamble
+- **Assumes knowledge**: The reader already knows the system
+- **Practical**: Concrete steps, not theoretical explanations
+- **No justification**: Don't explain why — if the reader asks why, they need an explanation, not a how-to
 
-### Cuándo dividir un how-to
+### When to split a how-to
 
-- Más de 10 pasos → dividir en how-tos más específicos
-- Cubre más de un problema → un how-to por problema
-- Tiene secciones de explicación → extraer la explicación a explanation/
+- More than 10 steps → split into more specific how-tos
+- Covers more than one problem → one how-to per problem
+- Has explanation sections → extract explanation to explanation/
 
-### Ejemplo concreto
+### Concrete example
 
-```markdown
+````markdown
 ---
-created: "2024-03-10"
+created: '2024-03-10'
 status: active
 type: how-to
 tags: [auth, jwt, middleware]
 ---
 
-# Cómo agregar autenticación JWT a una API existente
+# How to add JWT authentication to an existing API
+
+## When to use this
 
-## Cuándo usar esto
-Cuando tienes una API Express funcionando y necesitas proteger endpoints con JWT.
+When you have a working Express API and need to protect endpoints with JWT.
 
-## Pasos
+## Steps
 
-1. Instalar dependencias:
+1. Install dependencies:
 
-\`\`\`bash
+```bash
 npm install jsonwebtoken bcryptjs
-\`\`\`
+```
+````
 
-2. Crear middleware de auth en `src/middleware/auth.js`:
+2. Create auth middleware at `src/middleware/auth.js`:
 
-\`\`\`javascript
-const jwt = require('jsonwebtoken');
+```javascript
+const jwt = require('jsonwebtoken')
 
 function authMiddleware(req, res, next) {
-  const token = req.headers.authorization?.split(' ')[1];
-  if (!token) return res.status(401).json({ error: 'Token requerido' });
+  const token = req.headers.authorization?.split(' ')[1]
+  if (!token) return res.status(401).json({ error: 'Token required' })
 
   try {
-    req.user = jwt.verify(token, process.env.JWT_SECRET);
-    next();
+    req.user = jwt.verify(token, process.env.JWT_SECRET)
+    next()
   } catch {
-    res.status(401).json({ error: 'Token inválido' });
+    res.status(401).json({ error: 'Invalid token' })
   }
 }
 
-module.exports = authMiddleware;
-\`\`\`
+module.exports = authMiddleware
+```
 
-3. Proteger endpoints:
+3. Protect endpoints:
 
-\`\`\`javascript
+```javascript
 const auth = require('./middleware/auth');
 app.get('/api/profile', auth, (req, res) => { ... });
-\`\`\`
-
-## Resultado esperado
-Los endpoints protegidos requieren un JWT válido en el header `Authorization: Bearer <token>`.
 ```
 
-### Anti-patrones de how-to
+## Expected result
+
+Protected endpoints require a valid JWT in the `Authorization: Bearer <token>` header.
+
+````
+
+### How-to anti-patterns
 
-| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
+| Anti-pattern | Why it's bad | What to do instead |
 |-------------|----------------|----------------------|
-| Explicar conceptos básicos | El lector ya debería saberlo | Link a tutorial si necesita base |
-| Narrativa o storytelling | No es lo que busca el lector | Pasos directos y enumerados |
-| Múltiples soluciones alternativas | Confunde al lector | Una solución, la mejor práctica |
-| Prerequisitos extensos | Si necesita mucho setup, es un tutorial | Simplificar o link a tutorial |
-| "Opcionalmente puedes..." | Genera incertidumbre | Un camino claro |
+| Explaining basic concepts | The reader should already know | Link to tutorial if needed |
+| Narrative or storytelling | Not what the reader is looking for | Direct, numbered steps |
+| Multiple alternative solutions | Confuses the reader | One solution, best practice |
+| Extensive prerequisites | If it needs lots of setup, it's a tutorial | Simplify or link to tutorial |
+| "Optionally you can..." | Creates uncertainty | One clear path |
 
 ---
 
-## Patrones de Referencia
+## Reference Patterns
 
-### Estructura canónica
+### Canonical structure
 
 ```markdown
-# [Nombre del sistema/API/interfaz]
+# [System/API/interface name]
 
-## [Sección principal]
+## [Main section]
 
-| Parámetro | Tipo | Requerido | Descripción | Default |
+| Parameter | Type | Required | Description | Default |
 |-----------|------|-----------|-------------|---------|
 | ...       | ...  | ...       | ...         | ...     |
 
-## Códigos de respuesta
+## Response codes
 
-| Código | Significado | Cuándo se retorna |
+| Code | Meaning | When returned |
 |--------|------------|-------------------|
 | ...    | ...        | ...               |
 
-## Ejemplos
-[Un ejemplo mínimo por cada caso de uso principal]
-```
+## Examples
+[One minimal example per main use case]
+````
 
-### Tono
+### Tone
 
-- **Neutral y factual**: Sin opiniones, sin narrativa
-- **Estructurado**: Tablas > listas > prosa
-- **Completo**: Incluir TODOS los parámetros, TODOS los casos
-- **Sin explicaciones**: Si necesita explicarse, linkear a explanation/
+- **Neutral and factual**: No opinions, no narrative
+- **Structured**: Tables > lists > prose
+- **Complete**: Include ALL parameters, ALL cases
+- **No explanations**: If it needs explaining, link to explanation/
 
-### Pistas para auto-generación
+### Auto-generation tips
 
-Si el código tiene:
-- **OpenAPI/Swagger**: Generar referencia desde el spec
-- **TypeScript interfaces**: Extraer tipos y comentarios JSDoc
-- **JSON Schema**: Usar el schema como base
-- **CLI con `--help`**: Capturar la salida completa
+If the code has:
 
-### Qué incluir siempre
+- **OpenAPI/Swagger**: Generate reference from the spec
+- **TypeScript interfaces**: Extract types and JSDoc comments
+- **JSON Schema**: Use the schema as base
+- **CLI with `--help`**: Capture the complete output
 
-- Todos los parámetros/props/campos con tipo y descripción
-- Valores por defecto
-- Valores permitidos (enums)
-- Restricciones (min, max, formato)
-- Códigos de error
-- Ejemplos mínimos por cada caso principal
+### What to always include
 
-### Anti-patrones de referencia
+- All parameters/props/fields with type and description
+- Default values
+- Allowed values (enums)
+- Constraints (min, max, format)
+- Error codes
+- Minimal examples per main case
 
-| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
-|-------------|----------------|----------------------|
-| Prosa narrativa | La referencia debe ser consultable | Tablas y listas |
-| Ejemplos sin contexto | No se sabe cuándo usar cada uno | Un ejemplo por caso de uso |
-| Parámetros parciales | El lector no puede confiar en la doc | Documentar TODO o indicar qué falta |
-| Explicar el porqué | No es el lugar | Link a explanation/ |
-| Obviar edge cases | Sorprende al lector | Documentar todos los casos |
+### Reference anti-patterns
+
+| Anti-pattern             | Why it's bad                  | What to do instead                      |
+| ------------------------ | ----------------------------- | --------------------------------------- |
+| Narrative prose          | Reference should be scannable | Tables and lists                        |
+| Examples without context | Don't know when to use each   | One example per use case                |
+| Partial parameters       | Reader can't trust the doc    | Document ALL or indicate what's missing |
+| Explaining why           | Not the place                 | Link to explanation/                    |
+| Ignoring edge cases      | Surprises the reader          | Document all cases                      |
 
 ---
 
-## Patrones de Explicación
+## Explanation Patterns
 
-### Estructura canónica
+### Canonical structure
 
 ```markdown
-# [Tema o pregunta que se responde]
+# [Topic or question being answered]
+
+## Context
 
-## Contexto
-[Por qué existe, qué problema aborda]
+[Why it exists, what problem it addresses]
 
-## Cómo funciona
-[Vista general conceptual — sin código]
+## How it works
 
-## Alternativas consideradas
-[Qué otras opciones existían]
+[Conceptual overview — without code]
 
-## Implicaciones
-[Qué significa para el presente y futuro]
+## Alternatives considered
+
+[What other options existed]
+
+## Implications
+
+[What it means for the present and future]
 ```
 
-### Tono
+### Tone
 
-- **Discursivo y analítico**: Como una conversación con un colega experto
-- **Conectivo**: Relacionar con otros conceptos, ADRs, decisiones
-- **Histórico**: Contar la historia de por qué se llegó aquí
-- **Sin código** (o mínimo): El foco es el entendimiento, no la implementación
+- **Discursive and analytical**: Like a conversation with an expert colleague
+- **Connective**: Relate to other concepts, ADRs, decisions
+- **Historical**: Tell the story of how we got here
+- **No code** (or minimal): Focus is understanding, not implementation
 
-### Cuándo es necesaria una explicación
+### When an explanation is needed
 
-- Un ADR necesita más contexto del que cabe en 1-3 oraciones
-- Un concepto se referencia en múltiples how-tos/tutoriales y merece su propio espacio
-- Alguien preguntó "¿por qué hicimos esto así?" más de una vez
-- Hay confusión recurrente sobre un tema
+- An ADR needs more context than 1-3 sentences can provide
+- A concept is referenced across multiple how-tos/tutorials and deserves its own space
+- Someone asked "why did we do it this way?" more than once
+- There's recurring confusion about a topic
 
-### Vinculación con ADRs
+### Linking with ADRs
 
 ```markdown
-Para la decisión formal, ver [[ADR-003-event-sourcing]].
-Este documento explica el contexto y las implicaciones en mayor detalle.
+For the formal decision, see [[ADR-003-event-sourcing]].
+This document explains the context and implications in greater detail.
 ```
 
-### Anti-patrones de explicación
+### Explanation anti-patterns
 
-| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
-|-------------|----------------|----------------------|
-| Instrucciones paso a paso | Eso es un tutorial o how-to | Enfocarse en el porqué |
-| Listar todas las opciones de config | Eso es referencia | Explicar la lógica detrás |
-| Sin contexto histórico | Pierde el valor de la explicación | Incluir cómo se llegó ahí |
-| Demasiado abstracto | No ayuda a entender | Usar analogías concretas |
-| Repetir el ADR palabra por palabra | No agrega valor | Expandir con contexto y matices |
+| Anti-pattern               | Why it's bad                   | What to do instead              |
+| -------------------------- | ------------------------------ | ------------------------------- |
+| Step-by-step instructions  | That's a tutorial or how-to    | Focus on why                    |
+| Listing all config options | That's reference               | Explain the logic behind        |
+| No historical context      | Loses the value of explanation | Include how we got here         |
+| Too abstract               | Doesn't help understanding     | Use concrete analogies          |
+| Repeating the ADR verbatim | Adds no value                  | Expand with context and nuances |
 
 ---
 
-## Anti-patrones Transversales
+## Cross-cutting Anti-patterns
 
-### Anti-patrones que aplican a TODOS los tipos
+### Anti-patterns that apply to ALL types
 
-| Anti-patrón | Descripción | Solución |
-|-------------|-------------|----------|
-| **Documento camaleón** | Intenta ser dos tipos a la vez | Un doc = un tipo. Separar. |
-| **Contenido placeholder** | "TODO: agregar contenido" | Escribir contenido real o no crear |
-| **Sin frontmatter** | Archivo sin metadatos YAML | Siempre incluir frontmatter |
-| **Sin fecha** | No se sabe cuándo se creó | Siempre incluir `created` |
-| **Términos sin definir** | Jerga sin referencia a CONTEXT.md | Definir o linkear |
-| **Enlaces rotos** | Referencias a archivos que no existen | Verificar antes de publicar |
-| **Contenido duplicado** | Misma info en múltiples archivos | Referenciar, no duplicar |
-| **Sin verificación** | No hay forma de saber si está actualizado | Incluir `last-reviewed` en frontmatter |
+| Anti-pattern            | Description                            | Solution                               |
+| ----------------------- | -------------------------------------- | -------------------------------------- |
+| **Chameleon document**  | Tries to be two types at once          | One doc = one type. Separate.          |
+| **Placeholder content** | "TODO: add content"                    | Write real content or don't create     |
+| **No frontmatter**      | File without YAML metadata             | Always include frontmatter             |
+| **No date**             | Don't know when it was created         | Always include `created`               |
+| **Undefined terms**     | Jargon without reference to CONTEXT.md | Define or link                         |
+| **Broken links**        | References to non-existent files       | Verify before publishing               |
+| **Duplicate content**   | Same info in multiple files            | Reference, don't duplicate             |
+| **No verification**     | No way to know if it's updated         | Include `last-reviewed` in frontmatter |