Anexo H — Heurísticas de calidad de código y de usabilidad

Estado: APROBADO Y EN PRODUCCIÓN. No queda ninguna decisión abierta: la forma (D-043 y D-044), los interruptores (D-045 y D-046), el tablero (D-047) y las severidades iniciales con el peso de la accesibilidad (D-048, sección 10) están decididos. El documento está publicado en los ocho idiomas del método y sus dos prompts forman parte de la API de prompts: desde ahí, build/prompts.mjs exige el texto inglés idéntico byte a byte en los ocho o la construcción falla. Fecha: 2026-10-22.

Registro de las decisiones de este anexo: docs/DECISIONES.md, D-043 a D-048. El tablero de cumplimiento (sección 12) quedó decidido con dos cifras en D-047. El trabajo de implementación vive en PND-002.

1. Qué falta hoy, y por qué

El peldaño 9 ya mide el código y lo hace con una compuerta que no deja pasar: un formateador único, límites de tamaño (trescientas líneas por archivo, cuarenta por función), complejidad por función, código duplicado, código muerto, dependencias declaradas y usadas, cobertura con trinquete y pruebas de mutación donde hay usuarios reales. El número queda escrito en docs/CODE_QUALITY.md. Eso está resuelto.

Lo que no está resuelto es la otra mitad del producto. Verifiqué el corpus de peldaños: no hay una sola mención a usabilidad, a personas/perfiles ni a agrupación funcional. La interfaz se sostiene hoy en dos cosas: la captura que el dueño mira diez segundos y los casos de prueba manual. Las dos son buenas y las dos son humanas, caras y olvidadizas. Un sistema puede pasar la compuerta de calidad con honores y ser inusable: todo verde, y la persona no encuentra dónde cobrar.

Y hay un problema de segunda capa que sí es técnico pero se nota en la interfaz: cuando el mismo producto lo usan varios perfiles (administración, operación, consulta, cliente), las funcionalidades se habilitan en tres lugares distintos —la base, el menú y el guard de la ruta— que se escriben en momentos distintos y se desincronizan solos. El síntoma es siempre el mismo: alguien ve un botón que no le corresponde, o peor, alguien que sí tiene el permiso no encuentra la pantalla.

Las dos heurísticas que siguen atacan esas dos cosas con la misma forma: un catálogo corto de enunciados verificables, unos pocos instrumentos que los miden solos, y una vía de excepción declarada para cuando el proyecto necesita salirse.

2. El modelo: tres capas, una sola forma de regla

La tentación es hacer una lista de reglas y atarla al stack del primer proyecto. Eso envejece mal: la regla de React no aplica en Angular, la de Angular no aplica en un servidor con plantillas, y en dos años media lista queda muerta. La propuesta separa tres capas.

Capa 1 — Núcleo agnóstico (no se negocia). Enunciados sobre resultados, no sobre herramientas. "Hay un solo formateador y nadie discute con él" aplica igual en TypeScript, PHP o Go. El núcleo se enumera con identificadores estables y no cambia de proyecto en proyecto.

Capa 2 — Adaptador por stack (configurable). Para cada regla del núcleo, cada familia de frontend declara con qué se mide y con qué umbral. Un proyecto React con Vite, uno Next, uno Angular, uno de servidor con plantillas, uno mobile y uno de línea de comandos son seis adaptadores distintos del mismo núcleo. Acá vive todo lo que el usuario pidió como "configurable por frontend".

Capa 3 — Decisiones del proyecto (declaradas). Los umbrales concretos y las exenciones. No se inventan: se piden al dueño y quedan escritas, igual que el dimensionamiento del peldaño de arquitectura. Si un umbral no está declarado, corre el del adaptador y queda registrado como tal.

Cada regla se escribe siempre con la misma ficha de seis campos:

La excepción se declara, nunca se omite. Una regla se apaga con un registro de cuatro campos: identificador, motivo en una línea, quién lo autoriza (el dueño, no el agente) y fecha de revisión. Una regla apagada sin registro es un fallo de la compuerta, no una decisión. Es el mismo criterio que el método ya usa para no aceptar un límite subido "para pasar".

3. Los cuatro instrumentos

Ninguna heurística sirve si su verificación es una opinión. Son cuatro, y cada regla declara a cuál pertenece.

1. Compuerta automática. Corre en cada push y en el cierre de bloque. Devuelve verde o rojo. Es barata, es repetible y no discute. Mide todo lo que se puede contar.
2. Consulta a la matriz. La matriz de funcionalidades por perfil (ver B2) es un artefacto declarativo; el menú, el ruteo y los permisos se derivan de ella. Comprobar la matriz es comprobar la interfaz. Es la pieza que convierte una parte de la usabilidad en algo verificable por máquina.
3. Prueba de extremo a extremo por perfil. Para cada perfil declarado, un guion que entra como ese perfil y compara el conjunto de funcionalidades alcanzables contra la fila de la matriz: ni de menos ni de más. Es la prueba que atrapa las dos desincronizaciones típicas (el botón que sobra y la pantalla que falta).
4. Caso manual. Lo que ninguna máquina juzga: si la agrupación se entiende, si la tarea se completa sin ayuda, si el texto está en el idioma del usuario. Se ejecuta con personas y se registra, como ya manda el peldaño 10.

4. Parte A — Calidad de código

El núcleo extiende el peldaño 9: no lo reemplaza ni lo contradice, le pone nombre, severidad y adaptador a cada cosa que ya se mide, y agrega lo que hoy falta, que es la interfaz vista como código.

Las reglas CQ-12 a CQ-18 son las que hacen que "calidad de código" signifique algo en el frente. Sin ellas, el proyecto puede tener mutación al noventa por ciento y una pantalla que calcula el total con su propia aritmética en un componente: el peor de los dos mundos, porque el cálculo duplicado pasa todas las pruebas del backend.

Severidades iniciales (D-048). Bloquean desde el día uno las catorce reglas que tienen verificador y que no dependen de un umbral que haya que discutir: CQ-01 a CQ-06, CQ-08 y CQ-11 a CQ-17. CQ-09 bloquea donde hay usuarios reales, que es donde se mide. Avisan tres, y sólo tres: CQ-07 (tipos), CQ-10 (dependencias) y CQ-18 (accesibilidad), porque son las que necesitan que el proyecto calibre primero. El formateador, el linter, el tamaño y la complejidad no se aflojan: el peldaño 9 ya los bloquea hoy, y esto lo extiende, no lo reemplaza; la deuda heredada se resuelve con una excepción declarada o con la línea base del trinquete, nunca bajando la severidad. Y CQ-12 y CQ-14 son las dos únicas reglas de esta tabla que bloquean con rojo humano y no de máquina: se verifican al cierre del pendiente y con el caso manual delante, igual que UX-22 y UX-27, no en cada commit. Si el proyecto no puede sostener ese cierre, la regla baja a AVISA por decisión registrada, no por olvido.

Adaptador por familia de frontend. Un ejemplo de cómo se instancia la capa 2 (los nombres son ilustrativos; el proyecto elige y lo escribe):

Lo que cambia entre columnas es la herramienta y el umbral. Lo que no cambia es el enunciado. Eso es lo que hace la heurística agnóstica sin volverla decorativa.

5. Parte B — Usabilidad

Cinco familias. La primera y la segunda son las que el dueño pidió explícitamente; las otras tres existen porque sin ellas la agrupación y los perfiles se degradan igual, más lento.

B1 — Agrupación por convergencia funcional

La regla madre: una funcionalidad se agrupa por lo que la persona vino a hacer, no por el módulo del que salió. El código se organiza por entidades ("Factura", "Cliente", "Pago"); las personas no. Nadie entra al sistema a "gestionar entidades": entra a cobrar, a despachar, a cerrar el mes. Si el menú muestra las entidades, la persona hace de traductora. El menú es el trabajo.

B2 — Perfiles y funcionalidades habilitadas por perfil

Acá está la pieza que más rinde, y la razón es de ingeniería, no de diseño: la habilitación se declara una vez, en una matriz, y todo lo demás se deriva de ella. Hoy el error clásico es escribir el permiso tres veces (en el menú, en el guard de la ruta y en el filtro de datos) y que las tres se separen. Con la matriz como único productor, el menú, el ruteo, los permisos del servidor y los guiones de prueba son consumidores, y la simetría productor/consumidor que el método ya exige se vuelve verificable sola.

La matriz tiene cuatro columnas y una fila por funcionalidad: funcionalidad, casa (el grupo de B1), perfiles que la tienen, ruta de entrada. Nada más.

B3 — Estados, y qué ve la persona cuando algo no está

La mayoría de los reclamos de "no anda" son pantallas que no supieron decir "no hay nada", "está cargando" o "falló". Cuatro estados, siempre, en toda lista y toda pantalla de detalle.

B4 — Acciones y errores

B5 — Lenguaje y accesibilidad

6. Dónde se engancha, y qué artefactos produce

El anexo no inventa peldaños nuevos: se cuelga de los que existen. Eso evita duplicar compuertas y evita el destino habitual de las listas de usabilidad, que es ser leídas una vez.

Dónde va (D-043). Es transversal a los cuatro tramos, con el peso principal en el Bucle de Construcción (peldaños 5 a 12), que es donde se decide y se construye. No es un peldaño propio: un peldaño numerado obligaría a renumerar la escalera, alteraría el conteo de pasos y sometería el anexo a la traducción obligatoria de los contratos a los ocho idiomas antes de que la construcción pueda pasar en verde, sin agregar ninguna compuerta que el bucle no tenga ya.

Cómo se engancha (D-044). Una fuente canónica, cinco anclas y dos entradas previas. El texto de las reglas vive solo acá y los prompts lo citan; nunca lo copian. Repetir las cuarenta y cinco reglas dentro de los ocho prompts del bucle las diluye (compiten con el trabajo propio de cada peldaño y el agente las obedece distinto cada vez), las deriva (dos copias del mismo texto se desincronizan solas, que es el antipatrón que persigue el peldaño 11) y no las vuelve más transversales: lo que vuelve transversal a una regla es que cada bloque pase por la misma compuerta, no que la regla esté escrita en todas partes.

Estado (D-049). Las cinco anclas están enganchadas: el prompt inicial de los peldaños 5, 8, 9, 10 y 12 cita este anexo en los ocho idiomas, con una sola redacción inglesa idéntica en todos y su traducción local al lado. El documento se publica en el sitio con el resto del método en los ocho idiomas, y sus dos prompts entraron en docs/html/api/prompts.json como contrato anexo-h: desde ahí build/prompts.mjs los compara byte a byte en los ocho o la construcción falla.

Los peldaños 6, 7 y 11 reciben a lo sumo una línea: el 6 ya registra umbrales y excepciones como decisiones (es el lugar natural de la excepción declarada), y el 11 es donde entra a los golpes el caso de la matriz escrita en cuatro lugares. No se les agrega texto propio para no diluirlos.

Tres artefactos, todos en docs/: CODE_QUALITY.md (extendido), USABILITY.md (nuevo, con el resultado por regla y las excepciones declaradas) y PROFILE_MATRIX.md (la matriz, que es a la vez documento y fuente del menú).

7. Configuración

Un solo archivo por proyecto declara capa 2 y capa 3. Ejemplo con la forma propuesta, no con valores definitivos:

{
  "version": 1,
  "frontend": "react-vite",
  "medido_por": {
    "formato": "prettier",
    "lint": "eslint",
    "tipos": "tsc",
    "complejidad": "eslint-complexity",
    "duplicacion": "jscpd",
    "muertos": "knip",
    "cobertura": "vitest-coverage",
    "mutacion": "stryker",
    "accesibilidad": "axe-core"
  },
  "umbrales": {
    "lineas_por_archivo": 300,
    "lineas_por_funcion": 40,
    "caminos_por_funcion": 10,
    "cobertura_minima": 0,
    "mutacion_objetivo": 0
  },
  "excepciones": [
    {
      "regla": "CQ-17",
      "motivo": "informe imprimible heredado, sin tokens",
      "autoriza": "dueño",
      "revisar": "2027-01-31"
    }
  ]
}

Los dos ceros son deliberados y son la parte que importa: la cobertura mínima la fija el trinquete con lo medido, y el objetivo de mutación lo fija el dueño cuando el proyecto tiene usuarios. Si están en cero y nadie los declaró, la compuerta lo reporta como umbral no declarado en vez de inventarlo.

8. Las dos piezas, en la forma que usa el método

Calidad de código.

Usabilidad.

9. Lo que esta propuesta no hace

• No agrega un peldaño. Son cuarenta y cinco reglas transversales (18 de calidad y 27 de usabilidad), no una etapa nueva. Cuelgan de los peldaños que ya existen.
• No inventa un puntaje. Un número de "usabilidad 78" no dice qué arreglar y se optimiza en la dirección equivocada. Se reporta por regla. La sección 12 propone dos cifras derivadas, pero son un recuento de reglas con su asiento —no una nota de calidad ni de usabilidad— y no autorizan a cerrar nada.
• No reemplaza al dueño. La prueba del primer clic, la captura y la prueba de tarea siguen siendo humanas: son el único instrumento que distingue "funciona" de "sirve".
• No trae umbrales de fábrica. Los del adaptador son un punto de partida declarado; el proyecto que no declare los suyos los hereda y queda registrado como tal.
• No promete que la compuerta detecte la mala agrupación. Una máquina puede verificar que no haya duplicación ni huérfanas; si el grupo se llama "Gestión", lo tiene que ver una persona.

10. Las decisiones: qué quedó resuelto y qué falta

Resueltas

Cerrado en D-048, y las dos correcciones que arrastra

Las dos preguntas que trababan la escritura de los prompts ya están respondidas: la 1 quedó en la fila 5 y la 2 en la fila 6. Pero la recomendación que se aprobó tenía dos errores de hecho, y quedan escritos acá para que no vuelvan:

1. El defecto del conteo. Donde este anexo decía "veintisiete reglas" el número correcto es cuarenta y cinco: 18 de calidad (CQ-01 a CQ-18) y 27 de usabilidad (UX-01 a UX-27). La cifra vieja venía de un borrador que solo contaba la mitad. Corregido en las secciones 6 y 9 y anotado en D-048; el texto de D-044 se conserva tal como se escribió, porque una decisión es un registro y no se reescribe.
2. El formateador, el linter, el tamaño y la complejidad no se aflojan. Una versión anterior de esta recomendación los mandaba a "avisa" para no trabar proyectos con deuda heredada. No puede ser: el peldaño 9 ya los bloquea hoy, y esta extensión lo extiende, no lo reemplaza. La deuda heredada se resuelve con una excepción declarada —con motivo y fecha de revisión— o con la línea base del trinquete, no bajando la severidad de la regla.

Y una limitación declarada, porque es la única de su clase: CQ-12 y CQ-14 bloquean con rojo humano. Ninguna herramienta prueba que una pantalla no decide reglas de negocio. Se verifican al cierre del pendiente, con el caso manual delante y el mismo criterio que UX-22 y UX-27; si el proyecto no puede sostener ese cierre, bajan a AVISA por decisión registrada. Una regla que bloquea y que nadie verifica es peor que una regla que avisa.

Pendiente de calendario, no de decisión

La traducción. Hecha: el anexo existe en los ocho idiomas y sus dos prompts forman parte de la API de prompts, con el texto inglés idéntico byte a byte en las ocho versiones (lo exige D-043 y lo verifica build/prompts.mjs en cada construcción). El castellano sigue siendo el canónico: si alguna vez una traducción y el castellano discrepan, gana el castellano y la traducción se corrige en el mismo cambio.

11. Cómo se comprueba que la compuerta vigila

Una heurística que no cambia nada cuando se la prende o se la apaga no es una compuerta, es decoración. La prueba de aceptación de la implementación (PND-002) es un proyecto fixture con violaciones deliberadas de cada familia:

Lo que se mira no es solo el color: se mira que las dos líneas de apagado existan en el reporte. Un resultado verde sin esa línea es el único fallo que esta prueba no puede detectar sola por color, y por eso se verifica leyendo la salida.

12. El tablero de cumplimiento (DECIDIDO: dos cifras, D-047)

Estado. Decidido el 2026-10-22 en D-047: el tablero va con dos cifras, con la huella del reglamento, con trinquete, con lo humano fuera del porcentaje y con el asiento obligatorio. No autoriza a cerrar bloques. Lo que sigue es la especificación que la implementación (PND-002) tiene que cumplir.

Qué es. Un derivado determinista del resultado por regla que la compuerta ya emitió. No mide nada nuevo ni juzga nada nuevo: cuenta. Si el tablero pudiera cambiar el veredicto de una regla habría dos fuentes de verdad para lo mismo, que es exactamente lo que el anexo combate en UX-10 (la navegación se deriva de la matriz) y en CQ-14 (un solo lugar para el estado).

Qué no es. No es un criterio de aceptación. Ninguna cifra autoriza a cerrar un bloque: el verde o el rojo lo decide cada regla que bloquea, una por una. El tablero describe la tendencia y señala qué mirar. Si empieza a usarse como umbral de cierre, dejó de servir, porque el camino más corto para subir un número es apagar reglas.

Dos cifras, nunca una.

La razón de que sean dos: apagar una regla sube el cumplimiento y baja la cobertura. Con una sola cifra apagar es gratis y el tablero premia la ceguera. Con dos cifras que se mueven en direcciones opuestas, el atajo desaparece: para mostrar un tablero mejor hay que arreglar código, no apagar reglas. Y la cobertura no se puede subir sin medir.

La huella del reglamento. Cada registro guarda con qué vara se calculó: versión del catálogo, reglas activas y apagadas, adaptador de frontend y versiones de las herramientas. Sin eso, un 82 de ayer y un 91 de hoy no son la misma medida aunque se escriban igual: son dos reglamentos distintos y la serie es falsa. Dos cifras sin huella producen una ilusión de progreso, que es peor que no tener tablero. Si la huella cambia, el registro se marca como no comparable o el histórico se recalcula con la vara vigente; nunca se grafica junto sin decirlo.

Trinquete. El cumplimiento no baja de un bloque al siguiente sin una decisión registrada que lo explique. Es el mismo mecanismo que ya tiene la cobertura de pruebas en CQ-08: el número de hoy es el piso de mañana. Bajar no está prohibido; bajar sin registro, sí.

Lo que no entra en la cuenta. Lo que sólo puede juzgar una persona —la prueba del primer clic (UX-07), la prueba de tarea (UX-06), la captura (UX-27) y todos los casos manuales— se registra como pasado o fallado, por bloque, con nombre y fecha, y se reporta aparte como cobertura de verificación humana. No entra en el porcentaje de cumplimiento. Si se mezclan, el resultado es un número que es sesenta por ciento medición y cuarenta por ciento opinión, y nadie puede decir cuál es cuál. Por eso la sección 9 sigue valiendo: el tablero no inventa una nota de usabilidad, cuenta reglas.

Cómo se falsifica. Amplía la prueba de aceptación de la sección 11:

Dónde aparece. En el reporte honesto del peldaño 12 (ancla 5), y en este orden: primero el veredicto binario de la compuerta, después las dos cifras, después qué está apagado y hasta cuándo, después el movimiento contra el bloque anterior con su causa nombrada. Siempre con el asiento: bajó cuatro puntos: CQ-15, tres cadenas fuera del catálogo en la pantalla de cobro. Una cifra sin asiento es ruido; el asiento es lo que la vuelve accionable para un dueño que no lee código.

Riesgo declarado. El tablero lo va a leer el dueño, que no lee código, y por eso va a querer que suba. El número se convierte en el objetivo, y el objetivo desplaza al propósito. Las defensas son las de arriba, y son cinco: dos cifras que se contradicen al apagarse, la huella que impide comparar varas distintas, el trinquete que no deja bajar sin registro, lo humano fuera del porcentaje y el asiento obligatorio, con la compuerta que no se negocia por promedio. Si alguna de las cinco se cae, el tablero se apaga: un tablero mal usado hace más daño que no tenerlo.

13. Registro

Toda decisión de este anexo queda en docs/DECISIONES.md con fecha, autor, cita textual y archivos de impacto: D-043 (forma), D-044 (mecanismo), D-045 (interruptores), D-046 (disciplina del interruptor), D-047 (el tablero con dos cifras). La implementación y sus criterios de aceptación viven en PND-002.

No queda ninguna decisión abierta: la forma (D-043 y D-044), los interruptores (D-045 y D-046), el tablero (D-047) y las severidades iniciales con el peso de la accesibilidad (D-048) están decididas. El texto viaja en los ocho idiomas y forma parte de la API de prompts, que cierra el único punto que quedaba en el calendario.