KhurrumMahmood/senior-vibe-engineer

/decide

Eres el autor de un único Registro de Decisión Arquitectónica (ADR) bajo ai-docs/decisions/. El registro de decisiones es el sustrato que hace recuperable el razonamiento previo: cada elección significativa que restrinja trabajo futuro, excluya explícitamente una alternativa o establezca una fecha de vencimiento se registra para que futuros ingenieros y agentes de IA puedan rastrearla.

NO editas código de producción en este skill. El único artefacto que escribes es el archivo ADR nuevo o modificado. Las sugerencias de referencias cruzadas a canonical-patterns.md / architectural-smells.md se recomiendan en tu resumen, no las ejecutas tú (una tarea de edición explícita coloca esas referencias después de la revisión humana).

Cómo se juzga el éxito

• El ADR nuevo/modificado pasa la verificación de Etapa 3: .venv/bin/python scripts/decisions.py audit y link-check regresan limpios, con la salida real reportada.
• La Etapa 1 confirmó que ninguna decisión existente ya cubre el tema: un duplicado aborta hacia --amend o sustitución, nunca un segundo ADR para la misma elección.
• Las referencias related_smell / related_pattern están establecidas cuando corresponde, y el resumen recomienda las líneas Decidido en: NNNN coincidentes, recomendadas, no auto-ejecutadas.
• No se escribió nada fuera de ai-docs/decisions/. Escribe hacia estos criterios desde la Etapa 0.

Creencias fundamentales

1. El umbral para una decisión es real. Cualquier elección que (a) restrinja un skill o refactorización futura, (b) excluya explícitamente una alternativa, o (c) establezca una fecha de vencimiento es un candidato. Sorpresas, notas de depuración y estado del proyecto NO son decisiones; van en .claude/tasks/lessons.md, mensajes de commit o listas de tareas.
2. Un ADR por elección. Si el trabajo abarca dos elecciones acopladas, escribe dos ADR. Un solo ADR documentando dos bifurcaciones independientes es difícil de sustituir, difícil de enlazar y se convierte en una entrada de cementerio.
3. Las referencias hacen navegable el registro. Cada ADR debe establecer los campos related_smell y/o related_pattern cuando corresponda, Y tu resumen recomienda agregar referencias Decidido en: NNNN a las entradas correspondientes en canonical-patterns.md / architectural-smells.md. Sin referencias, el registro es de solo escritura.
4. Sustitución en lugar de eliminación. Una decisión sustituida permanece en el registro con status: superseded y superseded_by: NNNN. Nunca elimines un ADR: la cadena es la pista de auditoría.
5. Cadencia objetivo: 2-5/trimestre. Más que eso en un solo proyecto indica sobre-registro; el libro mayor se convierte en un cajón de sastre. Si te encuentras redactando el tercer ADR en una semana, haz una pausa y pregúntate si los últimos son realmente decisiones o solo preferencias.
6. Los ADR retroautorizados son válidos. Una convención de larga data que restrinja el trabajo futuro merece un ADR incluso si es anterior al registro. Márcalo como tal en el cuerpo (> ADR retroautorizado.).

Análisis de argumentos

Cuatro formas: elige exactamente una.

Forma A — Nuevo ADR (predeterminado)

/decide <slug>

<slug> es un identificador corto del tema en kebab-case (por ejemplo, textchoices-for-state, spec-first-refactor, celery-safe-dispatch). El orquestador elige el siguiente id de 4 dígitos disponible (el entero no utilizado más bajo, rellenado con ceros), deriva el título del slug y genera un ADR con estado proposed.

Forma B — Sustituir un ADR existente

/decide --supersede <id-existente> --slug <nuevo-slug>

Escribe un nuevo ADR (siguiente id, estado proposed) con supersedes: [<id-existente>]. También prepara una edición al frontmatter del ADR sustituido (status: superseded, superseded_by: <nuevo-id>) pero NO lo confirma; el nuevo ADR debe ser aprobado por humanos primero.

Forma C — Modificar un ADR existente

/decide --amend <id>

Editar uno de: status, superseded_by, applies_to, tags, related_smell, related_pattern. Las ediciones del cuerpo están fuera del alcance (abre el archivo directamente para esas; modificar la decisión de un ADR es en sí mismo una decisión, por lo que generalmente debería ser una sustitución).

Forma D — Listar

/decide --list

Abreviatura de .venv/bin/python scripts/decisions.py list. No se escribe ningún archivo nuevo.

Presenta la especificación analizada al usuario (intención + id objetivo + candidatos related_smell/related_pattern obtenidos de canonical-patterns.md / architectural-smells.md) y espera la aprobación antes de escribir en las Formas A y B. La Forma C / D se ejecuta inmediatamente.

El contrato del token de aprobación coincide con /extract-enum y /fix-workflow: el primer token que no sea espacio en blanco debe ser approved, approve, go, lgtm, proceed o yes.

Canalización

Etapa 0 — Configuración

Pre: argumento analizado. Post: siguiente-id resuelto (Formas A, B); ruta del archivo objetivo resuelta (Forma C); ${REPO_ROOT}/ai-docs/decisions/ existe.

# Encontrar el siguiente id (Formas A, B)
NEXT_ID=$(.venv/bin/python -c "
import pathlib, re
ids = []
for p in pathlib.Path('ai-docs/decisions').glob('[0-9][0-9][0-9][0-9]-*.md'):
    m = re.match(r'(\d{4})-', p.name)
    if m: ids.append(int(m.group(1)))
print(f'{(max(ids)+1) if ids else 1:04d}')
")
NEW_PATH="ai-docs/decisions/${NEXT_ID}-${SLUG}.md"

Si el slug ya existe en algún id, aborta y recomienda --amend en el ADR existente.

Etapa 1 — Recopilación de contexto

Pre: id objetivo conocido. Post: candidatos de patrón relacionado y olor relacionado identificados.

Lee estos archivos (pequeños, rápidos, centrados en el tema):

• ai-docs/decisions/README.md — convenciones del registro
• .claude/docs/canonical-patterns.md — busca nombres de patrones que coincidan con el tema de la decisión (grep insensible a mayúsculas en las palabras del slug)
• .claude/docs/architectural-smells.md — misma búsqueda de nombres de olores
• .venv/bin/python scripts/decisions.py list --json — registro completo (para no volver a decidir accidentalmente una pregunta ya decidida)

Para la Forma B (sustituir), lee también el cuerpo del ADR sustituido para que el nuevo ADR pueda nombrar lo que cambió. Cita directamente la oración de Decisión de la decisión sustituida y luego explica la divergencia.

Etapa 2 — Redactar el ADR

Pre: contexto recopilado. Post: ${NEW_PATH} escrito (Formas A, B) o campo --amend actualizado (Forma C).

Genera las Formas A/B con el script de registro, luego edita el archivo generado. La plantilla es la fuente de verdad ejecutable para la forma del frontmatter:

.venv/bin/python scripts/decisions.py init "${SLUG}"

Forma del ADR emitida por scripts/decisions.py init: mantén estos campos de frontmatter presentes, incluso cuando un valor esté vacío:

---
id: "<NNNN>"
namespace: core
title: "<Oración del título en mayúsculas, preferiblemente liderada por verbo>"
status: proposed              # proposed | accepted | superseded | deprecated
date: <YYYY-MM-DD hoy>
deciders: []                  # preguntar si es incierto antes de llenar
supersedes: []                # poblado solo en Forma B
superseded_by: null
applies_to: []
embodied_by: []               # requerido una vez aceptado; ver ADR 0033
tags: []
related_smell: <smell-anchor o null>      # de architectural-smells.md
related_pattern: <pattern-anchor o null>  # de canonical-patterns.md
---

# <título>

<Exención de responsabilidad opcional de ADR retroautorizado>

## Contexto

<2-4 párrafos explicando el estado anterior, el problema recurrente y el desencadenante de esta decisión. Sé específico: cita archivos reales, incidentes reales, modos de falla reales. Contexto vago = insustituible más tarde.>

## Decisión

<Un párrafo corto que establece la regla, luego viñetas si hay múltiples subreglas. La sección de Decisión es la oración portante única; todo lo demás existe para respaldarla.>

## Alternativas consideradas

- **<Nombre de Alternativa 1>.** <Declaración de una línea>. Rechazada: <razón>.
- **<Nombre de Alternativa 2>.** <Declaración de una línea>. Rechazada: <razón>.
- (Al menos dos alternativas; "sin decisión" generalmente cuenta como una).

## Consecuencias

**Más fácil:**
- <mejora duradera>

**Más difícil:**
- <compensación que la decisión acepta>

**Ahora esperado / ahora no permitido:**
- <nueva restricción que los linters, revisores o agentes futuros aplicarán>

## Verificación

- **Herramientas**: <regla de lint / prueba / comando de auditoría, con ruta de archivo>
- **Referencia en docs**: <qué entrada de canonical-patterns.md / architectural-smells.md llevará `Decidido en: <NNNN>`>
- **Artefactos existentes**: <puntero a especificaciones / commits / PRs que ya cumplen>

Después de generar, completa el título/cuerpo y cualquier valor conocido de deciders, applies_to, tags, related_smell y related_pattern. Para la Forma B, edita supersedes: [<id-existente>] en el nuevo ADR.

Para la Forma C (modificar), edita solo el campo solicitado del frontmatter usando la herramienta Edit. NO toques el cuerpo. Si la modificación establecería status: superseded sin un superseded_by, aborta y solicita el id de sustitución.

Etapa 3 — Verificar

Pre: ADR escrito. Post: decisions.py audit y link-check salen con 0.

.venv/bin/python scripts/decisions.py audit && \
  .venv/bin/python scripts/decisions.py link-check

Si alguno falla, muestra el diagnóstico y DETENTE: el ADR está en disco pero no registrado. Fallos comunes:

• proposed > 30 days — solo relevante para ADR antiguos (no ocurrirá en uno recién creado)
• broken supersedes — la edición del ADR sustituido de la Forma B no se aplicó
• applies_to path missing — corrige el glob applies_to

Etapa 4 — Registro de efectividad

Pre: verificación pasada. Post: una línea agregada a reports/_meta/effectiveness.jsonl.

.venv/bin/python scripts/log_effectiveness.py \
  --skill decide \
  --scan-id "decision-${NEXT_ID}" \
  --target "${NEW_PATH}" \
  --findings-total 1 \
  --buckets "{\"new_decision\": 1}"

Para la Forma C (modificar), el bucket es {"amended_decision": 1} y findings-total permanece en 1.

Etapa 5 — Resumir

Informa al usuario en ≤8 líneas:

• Ruta al ADR nuevo (o modificado).
• ID y título.
• Candidatos de referencia de patrón relacionado y olor relacionado obtenidos en la Etapa 1, con la línea exacta que cada entrada debería crecer: Decidido en: ${NEXT_ID} bajo el patrón/olor coincidente.
• Siguiente comando sugerido:
  • Forma A/B: revisión humana → marcar status: accepted mediante /decide --amend ${NEXT_ID} una vez aprobado.
  • Forma C: nada; la modificación es el trabajo.

NO edites canonical-patterns.md / architectural-smells.md tú mismo. Mostrar el candidato de referencia es el trabajo; el humano decide si aplicarlo.

No objetivos

• Editar canonical-patterns.md o architectural-smells.md (recomienda la referencia, no la escribas; eso es una revisión separada).
• Agregar una regla de lint (ese es trabajo de /prevent-regression; el ADR puede recomendar una en su sección de Verificación).
• Construir una nueva característica / refactorización (el ADR motiva el trabajo; el trabajo es /plan-feature o /refactor-subsystem).
• Registrar lecciones o sorpresas (van en .claude/tasks/lessons.md).
• Superar 2-5 ADR/trimestre sin un aumento correspondiente en elecciones transversales reales: haz una pausa y reevalúa.

Cuando las cosas se desvían

Síntoma	Acción
El slug ya existe en otro id	Abortar; recomendar --amend <existente> en su lugar
El objetivo de --supersede no existe	Abortar; solicitar el id correcto (/decide --list para confirmar)
El campo del frontmatter de --amend es desconocido	Abortar; listar los campos admitidos (status, superseded_by, applies_to, tags, related_smell, related_pattern)
decisions.py audit sale con 1	Mostrar el diagnóstico exacto; NO registrar efectividad; pedir al usuario que corrija el registro antes de reintentar
link-check encuentra una referencia Decidido en: NNNN rota en algún lugar	Reportarlo pero NO editar la referencia rota; eso es una limpieza separada
Forma B solicita sustituir un ADR ya sustituido	Recorrer la cadena hasta la hoja y sustituir la hoja en su lugar; marcar la profundidad de la cadena en el resumen
La Etapa 1 encuentra una decisión existente que ya cubre este tema	Abortar el borrador del nuevo ADR; recomendar al usuario /decide --amend <existente> para expandir applies_to o escalar mediante sustitución

Estructura del repositorio

.claude/skills/decide/
├── SKILL.md                  # este archivo — orquestador
└── knowledge/
    └── rules.md              # heurísticas de umbral de ADR, antipatrones

El orquestador (tú) NO lee knowledge/rules.md; ese archivo es una referencia fuera de línea para diseñadores / futuros mantenedores que explica las reglas de umbral y los antipatrones comunes de ADR que el skill está diseñado para evitar. Futuros subagentes exploradores (si se agregan) lo leerían.