Saltar a contenido

0003. El tablero vive en Markdown dentro del repositorio

  • Estado: Aceptada (ratificada por ENR al fusionar el PR #2, 2026-11-09). Sustituida en parte por 0032: el estado de las tarjetas pasa a GitHub Projects
  • Fecha: 2026-11-09
  • Decide: Enrique, al fusionar el PR del paso #001
  • Issue / PR: PR del paso #001

Contexto

El paso #001 de la guía aplicada pide un tablero con los estados del apéndice B.3 y los pasos #001–#020 cargados como tarjetas. La decisión D-24 elige GitHub como herramienta de producción (repositorio, incidencias, tablero y CI), pero no dice dónde vive el tablero. Hay que elegir antes de cargar las tarjetas, porque los agentes leen y actualizan el tablero en cada paso.

Opciones consideradas

  1. Tarjetas en Markdown dentro del repositorio (docs/production/board/).
  2. Pros: cumple la fuente única de verdad (B.1, decisión 0001): lo que no está en el repositorio no existe. Cada cambio de estado pasa por PR, con revisión e historial, igual que los entregables. Los agentes lo leen y lo editan con las mismas herramientas que el resto de documentos, sin permisos extra.
  3. Contras: no hay vista de columnas arrastrables; mover una tarjeta exige editar el archivo y el índice.
  4. Issues y GitHub Projects como tablero.
  5. Pros: vista de columnas, filtros y notificaciones de serie.
  6. Contras: el estado queda fuera del repositorio y fuera de los PR; los cambios no se revisan; los agentes necesitan acceso a la API de GitHub; el historial de la ficha (registro, procedencia) se dispersa en comentarios.
  7. Las dos a la vez como fuentes iguales.
  8. Contras: dos verdades que se desincronizan; contradice B.1.

Decisión

El tablero es Markdown dentro del repositorio: el índice en docs/production/board/README.md y una tarjeta por paso en docs/production/board/cards/, con la plantilla docs/production/board/step-card-template.md. Los cambios de estado entran por PR.

Los issues (formulario .github/ISSUE_TEMPLATE/step-card.yml) y un proyecto de GitHub (D-24) pueden reflejar el tablero como espejo opcional, para quien prefiera esa vista o para notificaciones. Nunca son fuente: si discrepan, manda la tarjeta en Markdown y se corrige el espejo.

Consecuencias

  • PROD mantiene el índice del tablero sincronizado con las tarjetas en cada PR que cambia un estado.
  • Se puede abrir un issue por tarjeta y enlazarlo desde ella, pero no es obligatorio.
  • Si el volumen de tarjetas (246 pasos más subpasos) hace incómodo el índice, se puede generar automáticamente desde las tarjetas sin cambiar esta decisión; se revisa en G1 junto con D-24.
  • Documentos afectados: CONTRIBUTING.md (cómo mover una tarjeta), README.md y docs/README.md (enlaces al tablero).