Registro de Decisiones
Visión General
Las decisiones son infraestructura duradera; la memoria y el historial del chat no lo son. El costo de un registro se paga una vez; el costo de una decisión perdida se paga cada vez que alguien reconstruye la intención a partir del código.
La Estructura del Registro
Toda decisión no trivial produce un registro con una estructura fija, para que cualquier lector sepa dónde mirar:
| Sección | Contenido |
|---|---|
| Arquitectura | La forma de la solución y los archivos clave |
| Modelo de Datos | Entidades, campos, relaciones |
| Decisiones (con POR QUÉ) | Cada elección acompañada de su justificación — por qué es obligatorio |
| Interfaces | Cómo otro código usa esto |
| Restricciones | Lo que debe seguir siendo cierto |
| Trampas | Errores no obvios para la siguiente persona |
| Alternativas Rechazadas | Lo que se consideró y descartó, y por qué — evita reabrir debates ya cerrados |
Los Tres Artefactos Complementarios
- Un índice de todas las decisiones con seguimiento explícito de dependencias (cuál se basa en cuál) y una sección reemplazado. Convierte un montón de registros en un grafo navegable.
- Un documento de "Consideraciones Futuras" — ideas aplazadas y preocupaciones conocidas, que se consulta al iniciar un nuevo trabajo para que nada quede olvidado en silencio. Las acciones pendientes de incidentes y las decisiones aplazadas con activador se colocan aquí.
- Un archivo — los registros reemplazados se mueven aquí en lugar de eliminarse. La historia se preserva, no se sobrescribe.
Referencia Rápida
- Convención de ubicación de registros:
docs/superpowers/decisions/YYYY-MM-DD-<tema>.mdcon frontmatter YAML (title,date,component,status,supersedes,dependencies). - Consideraciones Futuras vive en
docs/superpowers/future-considerations.md. Cada entrada lleva un estado (abierto/activado/hecho/descartado) y, cuando corresponda, el activador que debería reactivarla. Consúltalo al iniciar un nuevo trabajo. - El frontmatter alimenta el índice generado automáticamente — mantenlo preciso.
- El por qué y las alternativas rechazadas son las dos secciones de mayor valor. Un registro sin ellas es una mina terrestre.
- Escribe el registro en la etapa Registro del pipeline (ver
diseñando-antes-de-construir), después de Ejecutar.
Herramientas Incluidas
Esta skill incluye sus propios scripts y plantilla, por lo que funcionan en cualquier repositorio donde se instale la skill. Se encuentran junto a SKILL.md:
recording-decisions/
scripts/doc-archive.sh encuentra especificaciones/planes sin registro de decisión
scripts/index-rebuild.sh regenera el índice a partir del frontmatter de los registros
templates/decision-record.md
Ubícalos — la skill puede estar instalada por proyecto o globalmente:
for base in .claude/skills ~/.claude/skills; do
d="$base/recording-decisions/scripts"
[ -d "$d" ] && echo "$d" && break
done
doc-archive.sh [dir_especificaciones] [dir_planes] [dir_decisiones] [dir_archivo]
Enumera las especificaciones sin un registro de decisión correspondiente e imprime un aviso de conversión basado en la plantilla. Los valores predeterminados son docs/superpowers/{specs,plans,decisions,archive}.
index-rebuild.sh [dir_decisiones] [archivo_salida]
Reescribe docs/superpowers/index.md a partir del frontmatter de cada registro — una tabla Activa (componente, título, fecha, dependencias) y una tabla Reemplazada (componente, título, reemplazado por). Se regenera por completo, así que nunca lo edites manualmente.
Ambos son scripts bash sin dependencias externas: un proyecto que use esta skill no necesita yq, jq ni un gestor de tareas. Si los scripts faltan, los procedimientos anteriores son autocontenidos — realiza el trabajo directamente.
Por qué esto importa para el contexto
Las especificaciones y los planes son detallados a propósito; están escritos para un humano que sigue el razonamiento. Esa verbosidad se carga al contexto cada vez que Claude abre uno. Un registro de decisión conserva lo necesario para avanzar — decisiones, el por qué, interfaces, restricciones, trampas, alternativas rechazadas — en aproximadamente 30-50 líneas, mientras que la especificación original se mueve a archive/ donde sigue siendo legible para humanos y no cuesta nada hasta que se abre deliberadamente.
Cuándo NO usarlo
Los cambios triviales y evidentes no necesitan un registro. La prueba: ¿alguien preguntaría luego "por qué se hizo así"? Si la respuesta es sí, regístralo.
Justificación completa: Artículo II de la constitución, incluido en engineering-constitution/references/engineering-constitution.md.