git:20260702.b8fb11d to git:20261011.3fb211c

56 added, 31 removed. Audit A to A.

---

# machine-translated to es from skills/architecture-decision-record/SKILL.md — review: pending. Native fixes welcome via PR.

name: architecture-decision-record

- description: "Crea un Registro de Decisiones de Arquitectura (ADR) para cualquier decisión técnica. Úsalo cuando te pidan documentar una decisión técnica, escribir un ADR, registrar una opción de arquitectura, o capturar por qué se seleccionó una tecnología o enfoque. Produce un ADR estructurado con contexto, decisión, consecuencias e intercambios."

+ description: "Crea un Registro de Decisión de Arquitectura (ADR) para cualquier decisión técnica. Úsalo cuando necesites documentar una decisión técnica, escribir un ADR, registrar una elección arquitectónica o capturar por qué se seleccionó una tecnología o enfoque. Produce un ADR estructurado con contexto, decisión, consecuencias e intercambios."

---

- # Habilidad de Registro de Decisiones de Arquitectura (ADR)

+ # Habilidad de Registro de Decisión de Arquitectura (ADR)

- Esta habilidad produce un Registro de Decisiones de Arquitectura (ADR) completo siguiendo el formato Nygard — el estándar más ampliamente adoptado. Los ADR documentan el razonamiento detrás de decisiones técnicas significativas para que los miembros del equipo futuro entiendan no solo *qué* se decidió, sino *por qué*.

+ Esta habilidad produce un Registro de Decisión de Arquitectura (ADR) completo siguiendo el formato Nygard — el estándar más ampliamente adoptado. Los ADRs documentan el razonamiento detrás de decisiones técnicas significativas para que los futuros miembros del equipo entiendan no solo *qué* se decidió, sino *por qué*.

- ## Entradas Requeridas

+ ## Inputs Requeridos

- Pide al usuario esto si no está proporcionado:

- - **Número de ADR** (número secuencial en tu registro de ADR — p. ej. 012; o "próximo disponible" si no se conoce)

- - **Título de la decisión** (breve, p. ej. "Usar PostgreSQL como almacenamiento de datos principal")

+ Trabaja con lo que se proporciona. Si falta algo de esto, aun así produce el resultado completo: rellena cada vacío con una suposición razonable marcada como *(asumido, confirmar)* y lista esas suposiciones al final. Solo haz una pregunta cuando falta el tema central en sí (no hay nada sobre lo que escribir).

+ - **Número de ADR** (número secuencial en tu registro de ADR — p. ej. 012; o "siguiente disponible" si es desconocido)

+ - **Título de la decisión** (breve, p. ej. "Usar PostgreSQL como almacén de datos principal")

- **Contexto** (¿qué situación llevó a que esta decisión fuera necesaria?)

- - **Opciones consideradas** (al menos 2; si solo se proporciona 1, solicita alternativas que fueron consideradas o descartadas)

+ - **Opciones consideradas** (al menos 2; si solo se da 1, solicita alternativas que fueron consideradas o descartadas)

- **Decisión tomada** (qué opción fue elegida)

- **Razón de la elección**

- - **Estado** (Propuesto / Aceptado / Deprecado / Supersedido)

+ - **Estado** (Propuesto / Aceptado / Deprecado / Reemplazado)

- **Autor y fecha**

- **Contexto del equipo** (opcional — tamaño del equipo, experiencia relevante, restricciones organizacionales; ayuda a calibrar la formalidad y profundidad de la sección de Contexto)

## Formato de Salida

---

# ADR-[NNN]: [Título de la Decisión]

- **Fecha:** [AAAA-MM-DD]

- **Estado:** [Propuesto / Aceptado / Deprecado / Supersedido por ADR-NNN]

+ **Fecha:** [YYYY-MM-DD]

+ **Estado:** [Propuesto / Aceptado / Deprecado / Reemplazado por ADR-NNN]

**Autor(es):** [Nombre(s)]

- **Decisores:** [Quién tuvo la palabra final — individuo o equipo]

+ **Responsables de la decisión:** [Quién tuvo la palabra final — individuo o equipo]

---

## Contexto

- [3–6 oraciones. Describe la situación, restricciones y fuerzas en juego que hicieron que esta decisión fuera necesaria. Incluye: el problema que se está resolviendo, estado relevante del sistema, restricciones del equipo, presiones de cronograma, o requisitos innegociables. Escribe como si explicaras a alguien que se une al equipo en 18 meses que no tiene contexto previo.]

+ [3–6 oraciones. Describe la situación, restricciones y fuerzas en juego que hicieron necesaria esta decisión. Incluye: el problema a resolver, estado relevante del sistema, restricciones del equipo, presiones de cronograma o requisitos innegociables. Escribe como si explicaras a alguien que se une al equipo 18 meses después sin contexto previo.]

**Restricciones clave:**

- - [Restricción 1: p. ej. "Debe ser desplegable en las instalaciones para clientes empresariales"]

+ - [Restricción 1: p. ej. "Debe ser desplegable on-premise para clientes empresariales"]

- [Restricción 2: p. ej. "El equipo no tiene experiencia previa con Go"]

- - [Agrega tantas como sean relevantes]

+ - [Añade todas las que sean relevantes]

---

## Opciones Consideradas

Para cada opción, produce:

### Opción [N]: [Nombre]

**Descripción:** [Qué es esta opción — 1–3 oraciones]

**Ventajas:**

- [Ventaja 1]

- [Ventaja 2]

**Desventajas:**

- [Desventaja 1]

- [Desventaja 2]

**Por qué fue descartada (si no fue elegida):** [Razón honesta]

---

## Decisión

**Usaremos [opción elegida].**

- [2–4 oraciones explicando la decisión en lenguaje sencillo. Esto debería ser legible de forma aislada — alguien debería entender la decisión solo de este párrafo sin leer el documento completo.]

+ [2–4 oraciones explicando la decisión en lenguaje plano. Debería ser legible de forma aislada — alguien debería entender la decisión solo con este párrafo sin leer el documento completo.]

---

## Consecuencias

### Consecuencias Positivas

- [Qué esta decisión permite o mejora]

- [Qué riesgo mitiga]

### Consecuencias Negativas / Intercambios Aceptados

- [Qué estamos abandonando o asumiendo como resultado de esta decisión]

- [Deuda técnica o limitaciones introducidas]

- - [Qué debe ser verdadero ahora para que esta decisión siga siendo válida]

+ - [Qué debe ser verdadero para que esta decisión siga siendo válida]

### Riesgos

- [Qué podría hacer que esta decisión fuera incorrecta en retrospectiva]

- - [Qué nos triggrearía a reconsiderar esta decisión]

+ - [Qué nos haría reconsiderar esta decisión]

---

## Notas de Implementación

- [Incluye si la decisión tiene obstáculos de implementación no obvios, o si hay tickets/RFCs relacionados que los implementadores necesitarán. Omite solo si la decisión es puramente selección de herramientas sin ambigüedad de implementación.]

+ [Incluye si la decisión tiene gotchas de implementación no obvios, o si hay tickets/RFCs relacionados que los implementadores necesitarán. Omite solo si la decisión es puramente selección de herramientas sin ambigüedad de implementación.]

---

## Fecha de Revisión

- [Incluye a menos que la decisión sea permanente o evidentemente final. Especifica una condición de trigger — p. ej. "Revisar si el equipo crece más allá de 20 ingenieros o el tráfico supera 10M solicitudes/día" — no solo "debería ser revisado periódicamente".]

+ [Incluye a menos que la decisión sea permanente o evidentemente final. Establece una condición de disparo específica — p. ej. "Revisar si el equipo crece más allá de 20 ingenieros o el tráfico supera 10M requests/día" — no solo "debería revisarse periódicamente".]

---

+ ## Materiales Más Profundos

+ Esta habilidad se entrega con archivos de apoyo — úsalos cuando estén disponibles:

+ - **`references/decision-scoping.md`** — Qué Merece un ADR (y Qué Debe Contener el "Contexto"). Aplícalo mientras produces el resultado; contiene los juicios y decisiones de calibración que el resumen del método anterior comprime.

+ - **`templates/adr.md`** — una versión para rellenar del entregable con los gates de calidad inline. Ofrécela cuando el usuario quiera trabajar el documento él mismo en lugar de tenerlo generado.

+ ## Rúbrica de Puntuación (0–40)

+ Puntúa cualquier salida de esta habilidad antes de entregarla; 32+ es de calidad para producción.

+ | Dimensión | 0 | 5 | 10 |

+ |---|---|---|---|

+ | **Reconstrucción del contexto** | Asume que el lector ya conoce el problema y las presiones | Problema enunciado, pero faltan las fuerzas (restricciones del equipo, escala, plazo, evento que fuerza) | Un lector dos años después podría adivinar la decisión solo desde la sección de Contexto |

+ | **Honestidad de opciones** | Solo la opción elegida, u opciones rechazadas escritas como espantapájaros | ≥2 opciones, pero las razones de rechazo son circulares ("no cumplieron los requisitos") | Cada opción rechazada tiene fortalezas genuinas y una restricción perdedora específica vinculada a una presión del contexto |

+ | **Balance de consecuencias** | Todas las consecuencias son positivas | Negativas simbólicas sin especificidades operacionales | Los negativos nombran deudas reales, nuevas cargas operacionales y qué debe mantenerse verdadero para que la decisión se sostenga |

+ | **Disparadores de revisión** | No se indican riesgos o condiciones de revisión | "Revisar periódicamente" — sin condición medible | Condiciones de disparo específicas y medibles que invalidarían la decisión, con un responsable |

## Verificaciones de Calidad

- - [ ] El contexto explica el *por qué* — no solo el *qué*

+ - [ ] El Contexto explica el *por qué* — no solo el *qué*

- [ ] Al menos 2 opciones están documentadas (incluyendo las rechazadas)

- [ ] Las opciones rechazadas incluyen razones honestas de rechazo

- - [ ] Las consecuencias incluyen consecuencias *negativas* — ninguna decisión está libre de consecuencias

- - [ ] La decisión se expresa en lenguaje sencillo en la sección Decisión

- - [ ] La sección Riesgos identifica qué invalidaría esta decisión

- - [ ] La sección Contexto declara explícitamente el problema en sus primeras 1–2 oraciones (no asume que el lector sabe qué problema estaba resolviendo el equipo)

- - [ ] La explicación de "Por qué fue descartada" de cada opción rechazada nombra una restricción específica o intercambio (no una declaración circular como "no cumplió con nuestros requisitos")

+ - [ ] Las Consecuencias incluyen consecuencias *negativas* — ninguna decisión está libre de consecuencias

+ - [ ] La Decisión está enunciada en lenguaje plano en la sección de Decisión

+ - [ ] La sección de Riesgos identifica qué invalidaría esta decisión

+ - [ ] La sección de Contexto enuncia el problema explícitamente en sus primeras 1–2 oraciones (no asume que el lector sepa qué problema estaba resolviendo el equipo)

+ - [ ] La explicación "Por qué fue descartada" de cada opción rechazada nombra una restricción o intercambio específico (no una declaración circular como "no cumplió nuestros requisitos")

## Anti-Patrones

- - [ ] No escribas un ADR después de que la decisión ya haya sido completamente implementada y el equipo haya avanzado — los ADR escritos retrospectivamente a menudo omiten las razones reales y alternativas

+ - [ ] No escribas un ADR después de que la decisión ya haya sido completamente implementada y el equipo haya avanzado — los ADRs escritos retrospectivamente a menudo omiten las razones reales y alternativas

- [ ] No listes solo la opción elegida — las opciones rechazadas con razones honestas son la parte más valiosa de un ADR para lectores futuros

- [ ] No escribas consecuencias que sean todas positivas — cada decisión arquitectónica implica intercambios; un ADR sin consecuencias negativas no fue escrutinizado honestamente

- [ ] No dejes el estado como "Propuesto" indefinidamente — un ADR que nadie ha aprobado no está guiando las decisiones de nadie

- - [ ] No escribas contexto que asuma que el lector ya sabe qué problema estaba siendo resuelto — la sección contexto existe precisamente para lectores que carecen de ese trasfondo

+ - [ ] No escribas contexto que asuma que el lector ya sabe qué problema se estaba resolviendo — la sección de contexto existe precisamente para lectores sin ese antecedente

## Ejemplos de Uso

- "Escribe un ADR para usar [tecnología]"

- - "Documenta nuestra decisión de [opción arquitectónica]"

- - "Crea un registro de decisiones de arquitectura para [tema]"

- - "Ayúdame a escribir por qué elegimos [opción] sobre [alternativa]"

+ - "Documenta nuestra decisión de [elección arquitectónica]"

+ - "Crea un registro de decisión de arquitectura para [tema]"

+ - "Ayúdame a redactar por qué elegimos [opción] sobre [alternativa]"

+ ## Frases de Disparo de Ejemplo

+ - "Documenta una decisión técnica."

+ - "Escribe un ADR."

+ - "Registra una elección arquitectónica."

+ - "Captura por qué una tecnología."