@damenor/agent-docs 0.1.2 → 0.4.0

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

@@ -1,53 +1,56 @@
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: reference
-tags: [adr, decision, arquitectura, formato]
+tags: [adr, decision, architecture, format]
 ---
 
-# Formato ADR — Referencia Completa
+# ADR Format — Complete Reference
 
-## Qué es un ADR
+## What is an 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.
+An ADR (Architecture Decision Record) is a document that captures an important architectural decision, the context in which it was made, and its consequences. In this project, ADRs use a **minimal format**: title + 1-3 sentences.
 
-## Los 3 Criterios Obligatorios
+## The 3 Mandatory Criteria
 
-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
+### 1. Hard to revert
 
-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
+The decision has a high cost if reverted:
 
-**No es difícil de revertir**: Renombrar una variable, mover un archivo, cambiar un color en CSS
+- Significant refactoring time
+- Complex or risky data migration
+- Change affecting multiple teams or services
+- Contract that commits long-term resources
 
-### 2. Sorprendente
+**Not hard to revert**: Renaming a variable, moving a file, changing a CSS color
 
-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?"
+### 2. Surprising
 
-**No es sorprendente**: Usar Git, tener tests, usar Tailwind para CSS
+A newcomer to the project wouldn't expect this decision or would need additional context to understand it:
 
-### 3. Trade-off real
+- "Why do they use PostgreSQL and not MongoDB for this?"
+- "Why is auth in a separate service?"
+- "Why don't they use the team's standard framework?"
 
-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
+**Not surprising**: Using Git, having tests, using Tailwind for CSS
 
-**No es trade-off real**: No hay otra opción razonable, o la "alternativa" es claramente inferior
+### 3. Real trade-off
+
+There are valid alternatives with genuine advantages and disadvantages:
+
+- Option A: Faster but less maintainable
+- Option B: More expensive but more reliable
+- Option C: Team standard but not ideal for this case
+
+**Not a real trade-off**: No other reasonable option, or the "alternative" is clearly inferior
 
 ## Plantilla
 
 ```markdown
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: proposed | accepted | deprecated | superseded-by:ADR-NNN
 type: adr
 tags: [tag1, tag2]
@@ -56,6 +59,7 @@ 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]
@@ -63,61 +67,61 @@ tags: [tag1, tag2]
 <!-- Si se necesita más contexto, crear un archivo en explanation/ vinculado -->
 ```
 
-## Qué Califica como ADR — Ejemplos
+## What Qualifies as an ADR — Examples
 
-### Sí califica
+### Yes, qualifies
 
-| 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 |
+| Example                           | Hard to revert                  | Surprising                         | Real trade-off                 |
+| --------------------------------- | ------------------------------- | ---------------------------------- | ------------------------------ |
+| Modular monolith vs microservices | High rewrite cost               | Someone would expect microservices | Scalability vs complexity      |
+| Event sourcing for auditing       | Fundamental architecture change | Not the typical approach           | Consistency vs complexity      |
+| PostgreSQL over MongoDB           | Data migration + queries        | Semi-structured data in relational | ACID vs flexibility            |
+| Custom auth vs Auth0              | Change affects all users        | Auth0 is the team default          | Control vs speed               |
+| GraphQL instead of REST           | Contract change with clients    | REST is the standard               | Flexibility vs simplicity      |
+| Separate notification service     | Multi-team refactor             | Seems like same domain             | Scalability vs latency         |
+| No ORM, raw queries               | Requires data layer rewrite     | Team uses ORM by default           | Performance vs productivity    |
+| CQRS for reporting module         | Data pattern change             | Direct reporting is simpler        | Read performance vs complexity |
 
-### No califica
+### No, doesn't qualify
 
-| 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 |
+| Example                       | Why not                           | Failed criterion             |
+| ----------------------------- | --------------------------------- | ---------------------------- |
+| Using Git for version control | It's the industry standard        | Not surprising               |
+| Adding ESLint to the project  | Can be removed in 5 minutes       | Not hard to revert           |
+| Using React for the frontend  | It's the team's obvious choice    | Not surprising, no trade-off |
+| Naming variables in English   | It's the team convention          | No real trade-off            |
+| Using dotenv for env vars     | It's the standard, easy to change | Fails all 3 criteria         |
+| Adding prettier               | Removed in one commit             | Not hard to revert           |
 
-## Convención de Numeración
+## Numbering Convention
 
 ```
-ADR-001: Título de la primera decisión
-ADR-002: Título de la segunda decisión
+ADR-001: Title of the first decision
+ADR-002: Title of the second decision
 ADR-003: ...
 ```
 
-### Reglas
+### Rules
 
-- **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
+- **Sequential numbering**: ADR-001, ADR-002, ADR-003...
+- **No gaps**: Don't skip numbers. If an ADR is discarded, mark it as `status: deprecated` but the number is not reused
+- **File prefix**: `docs/adr/001-title-kebab-case.md`
+- **Unique title**: The title must be descriptive and not repeated
 
-### Nombre de archivo
+### File name
 
 ```
 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
+├── TEMPLATE.md          # Reusable template
+├── 001-modular-monolith.md
+├── 002-postgresql-over-mongodb.md
+├── 003-event-sourcing-audit.md
+└── 004-custom-auth-vs-auth0.md
 ```
 
-## Ciclo de Vida
+## Lifecycle
 
-### Estados de un ADR
+### ADR States
 
 ```
 proposed → accepted → deprecated
@@ -126,7 +130,7 @@ proposed → accepted → deprecated
 
 ### proposed
 
-El ADR se está discutiendo. Aún no es la decisión final.
+The ADR is being discussed. It's not yet the final decision.
 
 ```yaml
 status: proposed
@@ -134,7 +138,7 @@ status: proposed
 
 ### accepted
 
-La decisión fue tomada y se implementa.
+The decision was made and is being implemented.
 
 ```yaml
 status: accepted
@@ -142,7 +146,7 @@ status: accepted
 
 ### deprecated
 
-La decisión ya no aplica pero se mantiene por historial.
+The decision no longer applies but is kept for history.
 
 ```yaml
 status: deprecated
@@ -150,45 +154,47 @@ status: deprecated
 
 ### superseded
 
-Una decisión posterior reemplaza este ADR.
+A later decision replaces this ADR.
 
 ```yaml
 status: superseded-by:ADR-005
 ```
 
-En el ADR que reemplaza:
+In the replacing ADR:
+
 ```yaml
 status: accepted
 supersedes: ADR-003
 ```
 
-## Cuándo Expandir un ADR
+## When to Expand an ADR
 
-Si un ADR necesita más de 3 oraciones, crear un archivo en `explanation/` vinculado:
+If an ADR needs more than 3 sentences, create a linked file in `explanation/`:
 
 ```markdown
-# ADR-003: Event sourcing para auditoría
+# ADR-003: Event sourcing for audit
 
-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.
+We decided to use event sourcing for the audit module because regulatory
+requirements demand an immutable change history. We considered append-only
+tables but event sourcing provides better traceability. See [[explanation/event-sourcing]]
+for detailed context.
 ```
 
-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 |
+In `explanation/event-sourcing.md`:
+
+- Complete regulatory context
+- Evaluated alternatives with detailed pros/cons
+- Implications for the team and architecture
+- Implementation plan
+
+## Common Mistakes
+
+| Mistake                         | Solution                                              |
+| ------------------------------- | ----------------------------------------------------- |
+| Writing ADRs for everything     | Only write when all 3 criteria are met                |
+| 2-page ADRs                     | Minimal format: 1-3 sentences. Expand in explanation/ |
+| Inconsistent numbering          | Use sequential without gaps                           |
+| Forgetting to update status     | Change `status` when the decision changes             |
+| Not linking to explanations     | Add wikilinks to explanation/ when necessary          |
+| Repeating the same ADR          | Search existing ADRs before creating a new one        |
+| ADR without alternative context | Always mention what alternatives were considered      |