Bra1nZ/evidence-first-docs

Documentación basada en evidencia

La documentación no es una historia sobre el sistema. Es un registro de afirmaciones: cada afirmación material debe ser rastreable hasta un mecanismo y una evidencia, con los límites indicados en el mismo lugar que la afirmación.

Una frase segura es barata. El trabajo es permitir que el lector pueda distinguir qué fue probado, qué fue solo revisado y qué permanece abierto.

La regla fundamental

Cada afirmación material incluye cuatro elementos:

1. Mecanismo — qué en el sistema se supone que hace que la afirmación sea verdadera.
2. Evidencia — el artefacto de prueba: prueba, modelo, test, informe de análisis, traza, punto de referencia o registro de revisión.
3. Alcance — dónde se aplica la afirmación y qué está fuera del límite de confianza.
4. Estado — la etiqueta honesta más fuerte que la evidencia respalda.

Si falta uno de los cuatro, la afirmación no está lista. Reescríbela como una intención de diseño, un plan o una pregunta abierta – no la disfraces como un resultado.

Registro de afirmaciones

Mantén una tabla, en el documento o en un archivo de evidencia enlazado:

ID	Afirmación	Mecanismo	Evidencia	Alcance / TCB	Estado	Limitaciones	Última verificación
C-01	Solo el rol X puede escribir en la tabla T	Verificación de permisos + política de BD	Pruebas negativas T-04..T-11	PostgreSQL 14–17; rol Y, sesión sin rol	probado	El superusuario y el DBA están fuera del modelo de amenazas	2026-11-02

Reglas:

• Una fila por afirmación, no una fila por documento.
• Las afirmaciones deben ser falseables. "El sistema es seguro" no es una afirmación; "el rol Y no puede escribir en T a través de ningún punto de entrada soportado" sí lo es.
• Enlaza el artefacto, no solo el nombre de la herramienta. "SARIF" es un formato; la ruta del informe y el conjunto de reglas revisado son evidencia.
• Actualiza Última verificación cuando el artefacto se vuelva a ejecutar; la evidencia obsoleta es un hallazgo, no una formalidad.
• Mantén los resultados negativos. "Intentamos romperlo y fallamos debido a X" es evidencia; ocultarlo produce una falsa sensación de cobertura.

Escalera de estados

Usa la etiqueta más fuerte que la evidencia respalde, nunca una más fuerte:

Estado	Significado
probado	Prueba verificada por máquina de la propiedad indicada, con suposiciones y TCB declarados
verificado-por-modelo	Exploración exhaustiva o acotada de un modelo; indica el límite y la brecha modelo-código
probado	Pruebas ejecutadas que intentan la violación, con entorno y resultado registrados
refinado-estáticamente	Análisis estático o verificación de refinamiento; indica herramienta, reglas y hallazgos no resueltos
revisado	Solo revisión humana; sin evidencia ejecutable o formal
abierto	La afirmación existe pero la evidencia no; es un riesgo, no un resultado

Un estado más bajo no es un fracaso. Un estado inflado sí lo es.

No escribas verificado, probado, correcto, seguro, confiable, completo, garantizado, certificado o conforme sin un estado y alcance adyacentes. Si la palabra sobreviviría sin la evidencia, elimina la palabra.

Fortaleza de la evidencia

Prefiere evidencia que pueda fallar por la razón correcta:

1. Prueba formal de la propiedad indicada bajo suposiciones explícitas.
2. Verificación exhaustiva de modelo dentro de un límite indicado.
3. Pruebas basadas en propiedades o fuzzing con un corpus y oráculo registrados.
4. Pruebas negativas dirigidas que fallan cuando se elimina el mecanismo.
5. Análisis estático con un conjunto de reglas revisado y hallazgos clasificados.
6. Revisión de código con revisores nombrados y una lista de verificación.
7. Afirmación o anécdota.

La jerarquía no es absoluta: una prueba dirigida puede ser más fuerte que una prueba mal aplicada. Empareja la evidencia con la afirmación. Una prueba de un modelo que no refina el código no prueba el código. Una prueba que pasa porque la plataforma se negó primero no prueba tu guardia.

Alcance y límite de confianza

Indica el límite junto a la afirmación, no en un apéndice distante:

• Versiones y plataformas cubiertas.
• Actores privilegiados excluidos: superusuario, DBA, administrador de despliegue, administrador de secretos, sistema de compilación, operador.
• Suposiciones: primitivas criptográficas, reloj, red, almacenamiento, aislamiento de inquilinos, configuración.
• Qué se modela simbólicamente y qué se ejecuta realmente.
• Qué está fuera de alcance y por qué.

Una afirmación sin calificar es una afirmación sobre todo, lo cual casi siempre es falsa. "Seguro contra el rol Y en PostgreSQL 14–17 con la configuración documentada; el DBA está fuera del modelo" es honesta y útil.

Flujo de trabajo

1. Inventariar afirmaciones. Lee el texto y marca cada frase que afirme una propiedad, resultado, garantía o estado de cumplimiento.
2. Clasificar cada afirmación. ¿Es una intención de diseño, un requisito, un hecho de implementación, un resultado de prueba, un resultado formal o una afirmación de publicación?
3. Asignar un ID y un estado. Agrega mecanismo, evidencia, alcance, limitaciones y Última verificación.
4. Probar la afirmación contra el artefacto. Abre el informe, vuelve a ejecutar el comando o pide el artefacto faltante. No aceptes un nombre de archivo como evidencia.
5. Reescribir afirmaciones no respaldadas. Conviértelas en "intención de diseño", "planificado", "aún no verificado" o una pregunta abierta. Preserva la ambición; elimina la falsa certeza.
6. Verificar los negativos. Para cada afirmación de seguridad o corrección, nombra la prueba o análisis que intentó violarla. Si no hay ninguna, marca la afirmación como abierta.
7. Revisar el lenguaje. Elimina palabras prohibidas, cuantificadores vagos y absolutos sin calificar. Consulta references/banned-words.md.
8. Congelar la evidencia. Registra el comando, commit, entorno, fecha y ruta del artefacto para que un revisor pueda reproducir el resultado.
9. Filtrar la publicación. Una nota de publicación solo puede afirmar lo que el registro respalda. Enumera el riesgo residual y las afirmaciones abiertas explícitamente.

Lista de verificación de revisión

• Cada afirmación material tiene un ID, mecanismo, evidencia, alcance, estado y limitaciones.
• Cada afirmación probada nombra una prueba que puede fallar cuando se elimina el mecanismo.
• Cada afirmación verificada-por-modelo indica el límite y la brecha modelo-código.
• Cada afirmación probada indica las suposiciones y el TCB.
• Los resultados negativos y los fallos conocidos están presentes, no filtrados.
• Las fechas y versiones están actualizadas; la evidencia obsoleta está marcada como tal.
• Los actores privilegiados y las rutas fuera de alcance están nombrados.
• No aparece ninguna palabra prohibida sin evidencia y alcance adyacentes.
• El README, el documento de arquitectura, el contrato de API y la nota de publicación no se contradicen entre sí.
• Un lector puede reproducir la evidencia solo a partir del documento.

Antipatrones

1. Presente aspiracional. "El sistema garantiza..." cuando es un plan.
2. Evidencia por nombre de archivo. "Ver informe.pdf" sin resultado, alcance ni fecha.
3. Nombre de herramienta como prueba. "Verificado con análisis estático" sin reglas, hallazgos ni clasificación.
4. Lavado de alcance. Un resultado de prueba estrecho presentado como una garantía de todo el producto.
5. Absolutismo de suite verde. "Todas las pruebas pasan" sin decir qué pruebas, en qué plataformas y qué intentaron violar.
6. Simulación de cumplimiento. El nombre de un estándar utilizado como certificado; un mapeo no es una auditoría.
7. Limitaciones enterradas. La advertencia existe pero está lejos de la afirmación.
8. Certeza obsoleta. Un resultado de un commit antiguo presentado como actual.
9. Sin evidencia negativa. Solo se documentan los éxitos; los fallos y rechazos desaparecen.

Forma de salida

Cuando se te pida escribir o revisar un documento técnico, produce:

1. Un breve resumen de afirmaciones con recuentos por estado.
2. El registro de afirmaciones (en línea o enlazado).
3. Afirmaciones abiertas y riesgo residual, explícitamente separados de los resultados.
4. Alcance y suposiciones, junto a las afirmaciones que restringen.
5. Índice de evidencia con rutas, comandos, fechas y versiones.

Usa references/evidence-template.md para el registro y la forma de la nota de publicación. Usa references/banned-words.md antes de publicar. Si el repositorio incluye un mapeo de estándares, está en references/standards-map.md; la habilidad en sí no depende de un estándar.

Escala la salida al documento. Una nota de publicación corta necesita una tabla de afirmaciones compacta y una sección corta de riesgo residual, no un paquete de auditoría completo. Un archivo de evidencia para certificación necesita el registro completo, el índice de evidencia y el alcance. No confundas exhaustividad con longitud; cada fila debe contener información que el lector necesite.