cognitive-doc-design
Patrones de diseño de documentación cognitiva para borradores funcionales del proyecto. Prioriza legibilidad, progressive disclosure, tablas de decisión y evita texto denso.
SKILL.md.claude/skills/cognitive-doc-design/SKILL.md
GitHubCognitive Doc Design — Patrones de Documentación Cognitiva
Cuándo se usa
Aplicar SIEMPRE al redactar, estructurar o corregir borradores funcionales en el OKF del proyecto:
- Borradores de reglas de negocio (
F-Draft). - Notas de contexto, flujos y guías de diseño.
- Cualquier documento que vaya a ser leído por un humano (funcional, no técnico) o por un agente.
NO aplica a: log.md (audit log operativo) ni index.md (índice).
Principios
- Legibilidad por encima de completitud. Un lector debe entender la regla en menos de 30 segundos. Si necesita releer, el diseño falló.
- Progressive disclosure. Lo esencial primero, el detalle bajo demanda. Nunca sepultar la regla en contexto histórico.
- Tablas de decisión para reglas condicionales. Toda regla con condiciones (si X → Y) va en tabla. Prohibido anidar condiciones en prosa.
- Sin texto denso. Párrafos de más de 4 líneas → partir. Listas de más de 7 ítems → agrupar. Jerga innecesaria → eliminar.
- Idioma del lector (criollo para el funcional). Si el documento o la pregunta va a un funcional (no técnico), va en criollo: sin siglas en la cara del lector (
RN-…,P-…,[S-nn], "OKF", "bloque de derivación"), con un ejemplo concreto. Las siglas y la trazabilidad quedan por debajo (nota al pie o capa interna), para el sistema — no se pierden, no se muestran. Aplica SIEMPRE que se genere documentación o Historias de cara al funcional, sea desde un mockup o en el flujo normal. (Lo técnico para un dev — contrato, tests de una Tarea — mantiene su precisión: cada audiencia, su idioma.)
Estructura del borrador
Un borrador funcional se organiza así (en este orden):
- Propósito (2-3 líneas): qué resuelve este documento.
- Glosario (solo si hay términos ambiguos): término → definición en una línea.
- Reglas de negocio: numeradas con el prefijo del módulo (RN-<MOD>-001, RN-<MOD>-002…; nunca RN-nnn suelto), cada una con título descriptivo.
- Flujo (si aplica): pasos numerados o diagrama de secuencia simple.
- Dudas y preguntas: bloque explícito al final con lo que falta validar con el equipo funcional.
## Derivación a backlog(en toda ficha de flujo o funcional):Slices [S-nn],Capacidades [C-nn]yFlujos [F-nn]enumerados, y cada regla de la ficha asignada a un[F-nn]o declarada fuera de alcance con su motivo. Es el bloque que después fija el conteo 1:1 de Épicas/Features/Historias: sin él la ficha no se deriva, y si está incompleto el árbol sale mal de forma determinista — todos los LLM producen el mismo árbol equivocado. Lo incierto va⚠a confirmar por el humano. Detalle del formato: [[organizacion-y-trazabilidad]] §5.
Tablas de decisión
Formato canónico para reglas condicionales:
| # | Condición | Acción |
|---|---|---|
| 1 | <condición textual de la regla> |
<acción que corresponde> |
| 2 | <la condición contraria> |
<la otra acción> |
El ejemplo va con marcadores a propósito. Antes tenía un caso "real" (un umbral de antelación) que no corresponde a ninguna regla del Cerebro: un ejemplo inventado en una skill se copia como si fuera doctrina. Si necesitás un ejemplo concreto, tomá una regla que exista y citá su ruta.
Reglas:
- Una fila por combinación de condición → acción.
- Condiciones binarias (sí/no) → dos filas explícitas.
- Si hay más de 6 filas, agrupar por familia de condición (ej: "por ventana horaria", "por rol").
Consulta guiada al funcional (cuando falta info)
Cuando para completar algo (el bloque ## Derivación a backlog, una regla, un campo)
falta un dato que solo el funcional puede dar —o la IA tendría que inventar—, NO se
vuelca una lista técnica y se espera. Se conduce la consulta:
- Se dispara sola. El funcional no invoca nada: apenas aporta una pantalla/mockup o reglas para el backlog y aparece un hueco, la IA abre la consulta. (El funcional no sabe qué preguntar; la IA lo conduce — es el problema que esto resuelve.)
- Ítem por ítem, en criollo. Una pregunta a la vez, en lenguaje llano y con un ejemplo; se espera la respuesta antes de la siguiente. Nunca una lista técnica seguida de silencio.
- Reusa el patrón de decisión por ítem del [[cerebro-orquestador]] (Guardar / Ignorar / Editar y Guardar): misma mecánica, aplicada a completar la ficha.
- La trazabilidad va por debajo. Cada pregunta guarda el
[RN-…]/[P-…]que la origina (para el sistema); el funcional solo ve la pregunta en criollo. - No inventar. Lo que el funcional no cierra queda como pendiente; nunca se completa
por suposición. El bloque
## Dudas y preguntases el registro escrito; esta consulta es cómo se resuelve, conversando.
Anti-patrones
| Anti-patrón | Ejemplo | Reemplazo |
|---|---|---|
| Condicional anidado en prosa | "Si la solicitud es urgente y además el recurso tiene disponibilidad, entonces…" | Tabla de decisión |
| Párrafo-muralla | 8 líneas seguidas de regla + excepciones + antecedente | Partir en propósito + tabla + nota |
| Completitud ciega | Documentar 20 casos borde sin priorizar los que ocurren en la operación | Priorizar por frecuencia e impacto |
| Sin trazabilidad | Mencionar "según el manual" sin citar la fuente | Wikilink a fuentes.md y cita de sección |
Checklist de entrega (F-Draft)
- Propósito de 2-3 líneas al inicio.
- Reglas numeradas con título descriptivo.
- Condicionales en tablas de decisión (no en prosa).
- Sin párrafos de más de 4 líneas.
- Bloque "Dudas y preguntas" al final si hay algo sin validar.
- Wikilinks a
fuentes.mdo a la nota relacionada (trazabilidad). - Bloque
## Derivación a backlogcon[S-nn]/[C-nn]/[F-nn]enumerados (en fichas de flujo o funcionales). - Cada flujo de negocio que aparece en la prosa está enumerado como
[F-nn], o declarado fuera de alcance con su motivo escrito. Este es el chequeo que evita el error más caro del pipeline: un flujo que quedó en la prosa y no en la lista no puede convertirse en Historia nunca, en ningún LLM — la Regla de cardinalidad prohíbe crear nodos fuera de la enumeración. El error se vuelve determinista. - Cada regla de la ficha asignada a algún
[F-nn], o declarada fuera de alcance. Sin residuo: el bloque fija cuántas Historias, pero si no dice qué regla va en cuál, ese reparto lo decide el modelo y las reglas no asignadas desaparecen para todo lo que viene después.