ejklock/living-docs-skill

Living Docs

Trata la documentación como un sistema vivo que se mantiene sincronizado con el código, no como un artefacto de escritura única que se deteriora. La disciplina tiene una columna vertebral — cada pieza de conocimiento tiene exactamente un hogar, ese hogar está indexado, y nada estructural se envía sin su documento — y varios tipos de documentos que cuelgan de ella: una constitución, ADR, BDR, PRD, issues, investigación, diagramas de arquitectura y un índice de contexto semántico.

Esta habilidad es agnóstica respecto a la pila tecnológica. Gobierna cómo se organiza y mantiene la documentación, nunca qué tecnología utiliza un proyecto.

---

Invariantes principales (la columna vertebral)

Estos se mantienen en cada tipo de documento. Todo lo demás es detalle.

1. Documentación primero. Redacta el cuerpo en el repositorio (docs/…) antes de publicarlo en cualquier lugar externo (tracker, wiki). El archivo del repositorio es la fuente de verdad; la copia externa es un espejo.
2. Un hogar por hecho. Cada concepto, decisión o requisito vive exactamente en un archivo. Sin duplicación — en lugar de copiar, usa referencias cruzadas. La prosa duplicada es desviación a punto de ocurrir.
3. Indexado o no existe. Cada documento es accesible desde un índice (un index.md en su directorio, y el docs/index.md raíz del paquete al que enlaza la guía del proyecto). Sin archivos huérfanos.
4. Supercede, nunca reescribas la historia. Las decisiones y requisitos son registros de solo añadidura. Cuando algo cambia, marca el registro antiguo como supercedido y escribe uno nuevo — nunca edites silenciosamente el pasado.
5. Ningún cambio estructural sin su documento. Nuevo módulo, archivos movidos, cambio de esquema, nuevo flujo de datos → actualiza el documento relevante y su diagrama en el mismo cambio. No "lo documentaré después".

Ante la duda, deduce la acción correcta a partir de estos cinco. Los archivos de reglas a continuación son solo estos invariantes aplicados a cada tipo de documento.

---

Formato: conforme a OKF

Los cinco invariantes gobiernan la organización y el ciclo de vida; el Open Knowledge Format gobierna el formato de archivo para que el corpus se mantenga portátil y analizable por agentes. Cada documento del sistema es también un concepto OKF. Carga la habilidad okf-knowledge-format (que incluye la especificación) al redactar o verificar el formato.

OKF es una dependencia delgada e intercambiable — no un cimiento (riesgo de versión). OKF es v0.1 de un solo proveedor; una v0.2 incompatible hacia atrás es una posibilidad real. Los invariantes anteriores no dependen de OKF — dependen solo de un pequeño conjunto de campos de frontmatter, por lo que una rotura de OKF no puede derribar la capa de gobierno. Mantén el límite explícito:

• Requerido por Living Docs (el contrato de hecho que aplica scripts/lint-docs.sh): un type no vacío, y status + superseded_by en registros supercedidos. Estos son nuestros; sobreviven independientemente de OKF.
• Heredado de OKF (convenciones de formato): index.md/log.md reservados, okf_version raíz del paquete, enlaces relativos al paquete, el encabezado # Referencias (§8). Si OKF cambia, solo esta fila se mueve — vuelve a fijar la versión en la habilidad okf-knowledge-format y ajusta.

Dos reglas se aplican a cada archivo de concepto:

1. Frontmatter con un type requerido. Cada documento .md no reservado se abre con un bloque YAML de frontmatter cuyo type nombra el tipo de documento (Constitution, PRD, ADR, BDR, Issue, Context, Architecture View, Research, Reference). Recomendado: title, description, tags, timestamp. Living-docs añade claves de productor: status, supersedes, superseded_by. El estado se mueve al frontmatter — sin línea de cuerpo **Status:**.
2. Archivos reservados + enlaces relativos al paquete. La raíz del paquete es docs/. Los listados de directorio son index.md (OKF §6, sin frontmatter — excepto docs/index.md raíz del paquete, que lleva okf_version: "0.1"). log.md opcional registra el historial del directorio (§7). Enlaza con rutas relativas al paquete con prefijo / (/adr/0007-slug.md); lista fuentes bajo un encabezado # Referencias (§8), cada entrada formateada según rules/citation-conventions.md — estructura ABNT NBR 6023, siempre con el enlace, con etiquetas conectivas en el idioma del documento del proyecto (por defecto inglés: Available at: <URL>. Accessed on: <date>) según rules/doc-language.md.

---

Cadena de documentación

Cada cambio sigue esta cadena, desde la fuente de verdad fundamental hasta el código:

flowchart LR
  C[constitución] --> P[PRD]
  P --> A[ADR]
  P --> B[BDR]
  A --> I[issues]
  B --> I
  I --> K[código]

Artefacto	Rol
constitución	Fuente de verdad fundamental: qué es el producto, modelo de datos central, no negociables. Todos los demás documentos dependen de ella.
PRD	Qué debe hacer el sistema y por qué — especificación de requisitos de producto/funcionalidad.
ADR	Cómo está estructurado el sistema — decisión arquitectónica/de implementación y su justificación.
BDR	Qué debe hacer observablemente el sistema — entradas, salidas, efectos secundarios, escenarios Dado/Cuando/Entonces — y cómo se prueba cada uno (la matriz de diseño de pruebas; único hogar para "cómo probar", un issue de ejecución lo enlaza).
issues	Porciones de ejecución — unidades discretas de trabajo que remontan a ADR/BDR.
código	Implementación — cada comportamiento, estructura e interfaz especificados anteriormente, realizados.

---

Cuándo invocar

• Al establecer la documentación de un proyecto (crear la estructura docs/, el índice de documentación, directorios ADR/issue/BDR/constitución).
• La primera vez que living-docs se ejecuta en un proyecto (sin bloque ## Living Docs en la guía del proyecto) → haz la pregunta del modo de cumplimiento y persiste la respuesta → ver Modos de cumplimiento.
• Al adoptar living-docs en un proyecto existente/brownfield (decisiones ya tomadas pero no documentadas) → sigue Procedimiento → Adopción de living docs en un proyecto existente: inventaría las decisiones, confirma cada una con el usuario antes de registrar cualquier ADR, nunca retrocedas por inferencia únicamente.
• Al escribir o editar un ADR (una decisión arquitectónica/de implementación) → carga rules/adr-conventions.md + templates/adr.md.
• Al escribir o editar un PRD (una especificación de requisitos de producto/funcionalidad) → carga rules/prd-conventions.md + templates/prd.md.
• Al escribir o editar un BDR (comportamiento observable — entradas, salidas, escenarios Dado/Cuando/Entonces, y la matriz de diseño de pruebas para cómo se prueba cada uno) → carga rules/bdr-conventions.md + templates/bdr.md. Una decisión de estrategia de prueba (nivel/técnica no predeterminada, desviación de la barra) es un ADR con tags: [testing], no un nuevo tipo de registro (sin "TDR").
• Al especificar un requisito no funcional (rendimiento, disponibilidad, seguridad, escalabilidad) → un escenario de atributo de calidad vinculado a un instrumento en el PRD (rules/prd-conventions.md regla 9 + templates/prd.md); la decisión + la función de aptitud van en un ADR. No es un nuevo tipo de documento.
• Al establecer o modificar la constitución (alcance fundamental, modelo de datos, no negociables) → carga rules/constitution-conventions.md + templates/constitution.md.
• Al crear o editar un issue/ticket → carga rules/issue-workflow.md + templates/issue.md.
• Al registrar investigación (evaluación de tecnología, compensaciones externas) → carga la habilidad research-artifacts. Es dueña del formato de nota de investigación OKF (un archivo por nota, sin subcarpeta por investigación), la disciplina de la fuente, y la cadena trazable investigación → decisión → issue, y enlaza aquí para los artefactos ADR/BDR/issue. Se empareja con la habilidad deep-research.
• Al dibujar o actualizar un diagrama de arquitectura, flujo de datos o llamadas a herramientas → carga rules/architecture-diagrams.md + templates/architecture-index.md.
• Al definir un término o acrónimo que usan los documentos → agrégalo al glosario (docs/context/glossary.md), un hogar por término → carga rules/glossary-conventions.md + templates/glossary.md.
• Cuando un documento ha crecido demasiado o mezcla preocupaciones → divídelo en un índice semántico → carga rules/semantic-index.md + templates/context-index.md.
• Al aplicar la regla de mantenimiento sin desviación después de cualquier cambio estructural → carga rules/maintenance-invariant.md.
• Al redactar o verificar el formato OKF de cualquier documento (frontmatter type, index.md/log.md reservados, enlaces relativos al paquete, # Referencias) → carga la habilidad okf-knowledge-format.
• Al decidir qué idioma se usa para los documentos (por defecto inglés; el usuario puede anularlo al inicio de la sesión y fijarlo) → carga rules/doc-language.md.

---

Mapa de documentos

Tipo	Ubicación	Propósito	Mutabilidad
Guía del proyecto	CLAUDE.md / README.md (raíz)	Punto de entrada: alcance, pila, índice de documentación, flujos de trabajo obligatorios	Vivo — editar libremente
Constitución	docs/constitution.md	Fuente de verdad fundamental: alcance del producto, modelo de datos, no negociables	Solo añadidura una vez ratificada (registro de modificaciones)
Índice de contexto	docs/context/index.md + archivos de grupo	Vocabulario del dominio y del módulo, agrupado semánticamente	Vivo — editar libremente
Glosario	docs/context/glossary.md	Términos y acrónimos definidos una vez, en el idioma del documento (términos principales de acrónimos tal cual)	Vivo — editar libremente
Arquitectura	docs/architecture.md o docs/architecture/ + índice	Diagramas Mermaid vivos: estructura, modelo de datos, flujos, llamadas a herramientas	Vivo — debe coincidir con el código
ADR	docs/adr/NNNN-slug.md	Una decisión arquitectónica/de implementación	Solo añadidura (supercede)
BDR	docs/bdr/NNNN-slug.md	Una decisión de comportamiento observable	Solo añadidura (supercede o modifica)
PRD	docs/prd/NNNN-slug.md	Una especificación de requisitos de producto/funcionalidad	Solo añadidura una vez aceptado
Issue	docs/issues/NNNN-slug.md	Espejo del tracker (cuerpo), uno por ticket	Cuerpo editable; la copia publicada sigue
Investigación	docs/research/NNNN-<slug>.md (un solo archivo, sin subcarpeta; el número secuencial lidera, la fecha en frontmatter timestamp; termina en # Referencias)	Evidencia externa con afirmaciones referenciadas	Solo añadidura (la evidencia tiene fecha)

Cada directorio lleva su propio listado index.md (OKF §6, sin frontmatter). El "Índice de documentación" de la guía del proyecto enlaza al docs/index.md raíz del paquete. Ver rules/semantic-index.md para el contrato de indexación.

---

Procedimiento

Configuración de living docs en un proyecto nuevo

1. Haz la pregunta del modo de cumplimiento (ver Modos de cumplimiento → Pregunta de primera ejecución) antes que cualquier otra cosa, ya que ninguna preferencia está persistida aún. Registra la respuesta como el bloque ## Living Docs en la guía del proyecto; por defecto a strict si el usuario no tiene preferencia.
2. Crea la guía del proyecto (CLAUDE.md o equivalente) con una sección Índice de documentación y una sección Regla de mantenimiento (copia el texto de rules/maintenance-invariant.md). Usa templates/claude-hard-rules.md como punto de partida para la sección de reglas estrictas de la guía del proyecto — ya lleva el bloque de cumplimiento ## Living Docs; completa los marcadores de posición antes de hacer commit.
3. Crea docs/ con los directorios que el proyecto necesita (adr/, bdr/, issues/, prd/, research/, context/). Siembra docs/constitution.md desde templates/constitution.md. Añade el docs/index.md raíz del paquete (llevando okf_version: "0.1"), y dale a cada directorio su propio index.md desde el día uno — incluso si está casi vacío.
4. Siembra el índice de contexto (docs/context/index.md) con el vocabulario de dominio que exista, y el glosario (docs/context/glossary.md) con los términos y acrónimos que los documentos ya presuponen (rules/glossary-conventions.md). Ambos crecen a medida que se nombran conceptos.
5. Siembra el documento de arquitectura (docs/architecture.md) con las vistas Mermaid de alto nivel que el sistema ya tenga. Promueve a un directorio docs/architecture/ + índice cuando crezca (rules/architecture-diagrams.md).
6. Registra cualquier decisión ya tomada como ADR para que no se vuelva a discutir — pero confirma cada una con el usuario antes de registrar (ver Adopción de living docs en un proyecto existente, pasos 3–5); nunca retrocedas un ADR por inferencia únicamente.

Adopción de living docs en un proyecto existente (brownfield)

Una base de código existente ya incorpora decisiones que nunca se escribieron. El modo de fallo aquí es que el agente retroceda ADR por inferencia y los presente como establecidos — registrando decisiones que nunca se pidió al usuario confirmar. Por lo tanto, la adopción es un ejercicio de obtención de información, no de transcripción.

1. Haz la pregunta del modo de cumplimiento (primera ejecución) y persiste el bloque ## Living Docs, exactamente como para un proyecto nuevo.
2. Prepara el andamiaje sin decidir. Crea docs/ + el index.md de cada directorio, el docs/index.md raíz del paquete, y siembra el glosario/índice de contexto a partir del vocabulario ya presente en el código, el README y las guías del agente (CLAUDE.md / AGENTS.md). Esto es mecánico — no se toman decisiones aquí.
3. Lee el contexto existente primero, luego inventaría las decisiones — como candidatos, no como registros. Cosecha lo que el proyecto ya lleva: el código en sí, más el README, las guías del agente (CLAUDE.md / AGENTS.md), los manifiestos de paquetes, y cualquier nota de diseño o comentario. A partir de eso, produce una lista de las decisiones que soportan carga que el proyecto parece incorporar (pila, límites, modelo de datos, compensaciones clave). Aún no escribas ADR.
4. Presenta el inventario al usuario y confirma cada uno. Para cada candidato, indica la decisión inferida y las alternativas que parece haber descartado, y pide al usuario confirmar, corregir o descartarla — indaga en las que soportan carga (grill-me si está instalado). El usuario es dueño de la decisión; el agente solo saca a la superficie lo que el código implica.
5. Registra solo las decisiones confirmadas como ADR. Estos son registros de origen — no superceden nada. Captura la opción elegida y las alternativas rechazadas que el usuario confirmó. Un candidato que el usuario descarta, o uno cuya justificación nadie conoce realmente, no se inventa en un ADR.
6. Siembra el documento de arquitectura con las vistas Mermaid de alto nivel que el sistema ya tenga (rules/architecture-diagrams.md), luego reanuda el bucle de Mantenimiento a continuación.

Mantenimiento de living docs (cada tarea)

1. Antes de codificar: lee el modo de cumplimiento ## Living Docs de la guía del proyecto (si el bloque está ausente, esta es la primera ejecución — haz la pregunta de primera ejecución y persiste la respuesta). Luego lee la constitución, ADR, BDR y los [truncado para traducción]