Documentación de MindTune — cómo está armada y cómo se escribe

Convención fijada el 2026-09-20 (hilo Tinnitumetría, decisión D-D1 de Hayo). Esta carpeta es la fuente; la web privada docs.mindtune.cl se genera desde aquí (Hugo + Cloudflare Pages + Cloudflare Access). Nada se escribe dos veces: si algo está en la web y no está aquí, la web está mal.

Para quién y para qué

Para el equipo que vaya a revisar o modificar la app, hoy o en dos años: desarrolladores, clínicos del programa, un revisor externo, y los propios Hayo, Cowork y Claude Code cuando hayan olvidado por qué algo es como es. La pregunta que responde no es solo cómo funciona sino por qué así y no de otra manera: qué se consideró, qué se descartó, con qué evidencia, y qué habría que volver a mirar si cambia el contexto.

Las dos capas

Capa	Carpeta	Pregunta que responde	Quién la lee	Largo
1 — Cómo funciona	`como-funciona/`	¿Qué hace la app hoy, exactamente? Pantallas, textos, parámetros, datos que guarda, lo que el paciente ve y lo que no.	Cualquiera del equipo; el clínico que atiende a un paciente que usa la app; el revisor de Apple si hace falta.	1–3 páginas por tema. Sin citas, sin alternativas, sin historia. Presente indicativo.
2 — Por qué así	`por-que-asi/`	¿Por qué se decidió esto? Contexto, evidencia, alternativas consideradas y descartadas con sus razones, decisiones con fecha y autor, límites conocidos, qué revisar y cuándo.	El equipo desarrollador y clínico cuando quiera cambiar algo.	Lo que haga falta. Citas obligatorias.

Cada tema tiene las dos páginas con el mismo nombre de archivo (como-funciona/tinnitumetria.md y por-que-asi/tinnitumetria.md) y cada una enlaza a la otra en su primera línea. Un tema sin capa 2 es un tema cuya razón nadie escribió: se marca > Capa 2 pendiente arriba, no se disimula.

Relación con los documentos normativos

Los normativos (MindTune2027/app_piloto/*.md: roadmap, Design System, Plan Integrado, Perfil, Aprender, Consentimientos, Tinnitumetría…) siguen siendo lo que manda sobre cómo se construye la app y los mantiene Cowork. Los informes (INFORME_H*.md, raíz del repo) cuentan qué pasó en cada hito. Esta documentación no reemplaza a ninguno: los explica, los ordena por tema en vez de por hito, y enlaza a la sección exacta. Regla: la capa 1 se escribe desde el código y las capturas (lo que está, no lo que se especificó); la capa 2 se escribe desde los normativos, la bitácora §3-bis del roadmap, las decisiones D-xx del §4 y las revisiones de literatura. Cuando la capa 1 y el normativo no coinciden, eso es un desfase: se anota en la capa 1 con > ⚠️ Desfase: y como una fila de deuda.md. La página lo cuenta donde estorba; la tabla lo persigue hasta que alguien lo cierre. Un desfase que solo vive dentro de una página no lo junta nadie.

Decisión pendiente (no tomada): mover los normativos de OneDrive al repo. Hasta entonces, se enlazan por nombre de archivo y sección.

Estructura

docs/
  README.md                      ← este archivo
  como-funciona/
    _index.md                    ← mapa de la app en una página: pestañas, terapias, perfil, flujo de primer uso
    principios.md                ← las cuatro reglas de §0 del DS y las excepciones, en lenguaje llano
    <tema>.md
  por-que-asi/
    _index.md                    ← índice de decisiones D-xx por fecha, con enlace al tema que las explica
    <tema>.md
  glosario.md                    ← Ft, mMIDST, punto de mezcla, rasgo/estado, C1/C2/C3, -bis, oráculo v3.3…
  referencias.md                 ← bibliografía única (una entrada por fuente; las páginas citan por clave)
  deuda.md                       ← desfases y deuda normativa que encontró la documentación, con dueño
  sitio/                         ← lo que Hugo necesita (config, tema mínimo); no contiene contenido

Temas (uno por par de páginas; la lista crece): arquitectura-local-first · primer-uso-y-consentimientos · perfil-de-tinnitus · tinnitumetria · terapias-catalogo · mmidst · induccion-de-filtrado · inhibicion-residual · manejo-de-hiperacusia · musica-y-catalogo · sesion-y-pantalla-bloqueada · historial-y-bitacora · aprender · plataforma-clinica-y-panel · diseno-visual-y-movimiento · marca-animada · datos-privacidad-y-borrado · recomendaciones (cuando exista reglas_v1).

La capa 1 no lleva estado de hito

La cabecera dice contra qué commit y en qué fecha se verificó la página, no si el hito está ✅ o ⏳. El estado de los hitos tiene un solo dueño —la tabla de ROADMAP_MAESTRO.md §3— y duplicarlo acá garantiza que quede viejo: la primera página de esta carpeta nació diciendo «especificado, no implementado» el mismo día en que H8.2 se implementó, y quedó describiendo en futuro algo que ya existía. Una página de capa 1 se escribe en presente indicativo sobre lo que el código hace hoy; lo que está a medio hacer se dice en la línea del cuerpo que corresponde («hoy esa fila dice siempre No medido»), no en un rótulo de estado arriba.

Plantilla de la capa 1 — `como-funciona/<tema>.md`

# <Nombre visible del tema>
> Por qué así: [por-que-asi/<tema>.md] · Normativo: `<archivo>.md` §n · Código: `lib/features/<carpeta>/`
> Verificado contra `<hash>` el AAAA-MM-DD · Probado en iPhone: sí/no (H*-bis)

## Qué es, en tres frases
## Dónde está en la app (ruta de pestañas y pantallas)
## Paso a paso (lo que ve el paciente, con los textos literales)
## Parámetros y valores por defecto (tabla: nombre · valor · dónde se cambia · quién puede)
## Qué guarda y qué sube (tabla: dato · local · C1 · C2 · C3)
## Lo que NO hace (a propósito)
## Capturas (claro/oscuro)

Plantilla de la capa 2 — `por-que-asi/<tema>.md`

Sigue el formato de un registro de decisión (ADR, architecture decision record), extendido a lo clínico y teórico:

# <Tema> — por qué así
> Cómo funciona: [como-funciona/<tema>.md] · Decisiones: D-xx…D-yy (fechas) · Última revisión: AAAA-MM-DD

## 1. Contexto y problema (qué había antes, qué faltaba, qué obligaba a decidir)
## 2. Lo que dice la evidencia (resumen con cifras y citas por clave → referencias.md)
## 3. Alternativas consideradas (tabla: alternativa · a favor · en contra · por qué se descartó o se eligió)
## 4. Decisiones (una por fila: id · fecha · quién · qué · por qué en una línea)
## 5. Consecuencias (qué obliga, qué prohíbe, qué toca en otros temas)
## 6. Límites conocidos y riesgos (lo que sabemos que no resuelve)
## 7. Qué revisar y cuándo (disparadores: "si aparece X", "cuando haya n pacientes", "si Apple…")
## 8. Historia (hitos, informes, desviaciones declaradas)

Reglas de redacción, las mismas de la app: español, sin adular, decir de frente lo que no se sabe. Cada afirmación de estado lleva fuente (hash, archivo:sección, informe). Cada cifra clínica lleva cita. Las alternativas descartadas se escriben con la misma seriedad que la elegida: son lo que evita que alguien las reproponga sin saber que ya se pensaron.

Cómo se publica (resumen; detalle en `sitio/README.md`)

Hugo lee docs/ como contenido, con un tema mínimo propio (IBM Plex, tokens del Design System, dos columnas en escritorio, una en teléfono, buscador). Cloudflare Pages construye desde HayoBK/MindTune_Pilot_v2027 con raíz docs/sitio/ en cada push a main. Cloudflare Access (Zero Trust, plan gratuito hasta 50 usuarios) protege docs.mindtune.cl con código por correo a una lista de direcciones que administra Hayo. Nada de contraseñas compartidas.

Cómo se mantiene

Todo hito que cierre Claude Code deja en la §5 de su INFORME_H*.md qué páginas de docs/ tocó o hay que tocar. La skill mindtune-estado-y-tarea lo lee.
Todo hilo de Cowork que tome una decisión D-xx la agrega a por-que-asi/_index.md y a la §4 del tema.
Una vez por mes (o antes de mostrarle la app a alguien nuevo) se recorre como-funciona/ contra el simulador buscando desfases.