> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Metodología documental

Este repositorio no es el editor de workflows ni el backend de negocio, y
tampoco es el espejo de otro repositorio. Es la capa que convierte conocimiento
autorizado en documentación que una persona puede leer y un agente puede
localizar. Por eso el trabajo debe citar su fuente, hacer explícitos los
límites y poder repetirse cuando cambie el sistema.

## El ciclo que seguimos

```text
Inventariar → Investigar → Clasificar → Redactar
      ↑                                  ↓
  Revisar ← Publicar ← Validar ← Enlazar
```

1. **Inventariar:** localizar la estructura existente, las rutas canónicas, los
   índices y las redirecciones antes de editar.
2. **Investigar:** reunir evidencia de la fuente que manda para cada afirmación.
   Una lectura de plataforma debe ser de solo lectura; no se cambia un workflow
   para comprobarlo.
3. **Clasificar:** asignar dominio, tipo de página, audiencia, propietario y
   estado de verificación. Separar as-is, propuesta y pendiente.
4. **Redactar:** escribir primero en español y explicar el resultado, el alcance,
   el flujo, las excepciones y las fronteras del sistema.
5. **Enlazar:** dejar un único propietario por hecho y conectar índices, páginas
   relacionadas, glosario y fuentes sin copiar el mismo contrato en varios
   lugares.
6. **Validar:** comprobar metadatos, enlaces, índice de agentes, build, rutas
   publicadas y diagramas que formen parte del alcance.
7. **Publicar:** revisar el diff, hacer un cambio documental aislado y publicar
   solo cuando la evidencia y las comprobaciones sean suficientes.
8. **Revisar:** dejar visibles los datos temporales, los riesgos residuales y el
   siguiente paso para que otra lectura pueda actualizar la página sin empezar
   de cero.

## Principios

### La evidencia precede a la prosa

Cada afirmación importante debe poder responder tres preguntas: **qué fuente la
respalda, qué alcance tuvo la lectura y cuándo puede caducar**. La plataforma
manda sobre el estado de un workflow; el servicio manda sobre su contrato; la
aplicación que calcula una métrica manda sobre su definición; y un acuerdo de
negocio aprobado manda sobre una decisión.

Una nota, un resumen de Slack o un snapshot indirecto puede abrir una
investigación, pero no se convierte por sí solo en una capacidad productiva.
Cuando una fuente no está disponible, se escribe **por confirmar** o **no
encontrado**; no se rellena el hueco con una suposición.

### Un hecho, una página propietaria

La navegación se organiza primero por dominio y después por el tipo de página:

```text
src/pages/use-cases/<dominio>/
├── tutorials/    aprender un recorrido completo
├── how-to/       completar una tarea concreta
├── explanations/ entender contexto y decisiones
└── reference/    consultar contratos e inventarios
```

Un hecho tiene una sola página canónica. Otra página puede explicar su relación,
pero enlaza a la propietaria en lugar de mantener una copia que pueda divergir.
Si una página encaja en dos intenciones, se elige la intención principal y se
crea un enlace desde la otra sección.

### Estado y propuesta no se mezclan

Distingue al menos estas dimensiones:

* **verificado / por confirmar / no encontrado:** calidad y procedencia de la
  evidencia;
* **as-is / to-be / pendiente:** estado del producto o de la arquitectura;
* **live / latest / snapshot:** relación temporal entre versiones de plataforma;
* **canónico / working / generated / skeleton:** estabilidad de la página en el
  repositorio.

Una versión latest no es necesariamente la live. Un HTTP 200, una pantalla
visible o una métrica del dashboard prueban una observación técnica, no por sí
solos el resultado de negocio, la habilitación de una ruta o la entrega de un
caso.

### El público no es el control de acceso

`public`, `internal` y `shared` describen a quién está dirigida una página. No
son ramas paralelas ni controles de permisos. La seguridad efectiva pertenece a
la plataforma y a los owners del sistema; la documentación explica el contrato
sin publicar secretos, PII, cookies, tokens, credenciales, transcripts completos
ni exportaciones innecesarias.

### El cambio documental debe ser pequeño y reversible

Separamos la publicación de documentación de la release de un workflow, un
cambio de dashboard o una modificación de infraestructura. No se hacen hot
changes para obtener evidencia. Un cambio debe poder revisarse por diff,
revertirse sin arrastrar trabajo no relacionado y dejar claro qué sigue fuera
de alcance.

## Precedencia de fuentes

| Afirmación | Fuente que manda | Tratamiento de una fuente indirecta |
| --- | --- | --- |
| Estado, versión y nodos de un workflow | Plataforma, leída en el entorno indicado | Snapshot etiquetado como temporal; revalidar antes de cambiar. |
| Contrato de una API o tool | Servicio que atiende la llamada y su código | Documentar la implementación observada, no una intención. |
| Resultado de negocio, CI/CG o ticket | Backend owner del canal | No usar el dashboard como sustituto de la fuente de verdad. |
| Definición de una métrica o label | Aplicación que la calcula | Separar agregación, fixture y resultado real. |
| Decisión o política | Registro aprobado por su responsable | Un mensaje o hilo requiere contexto y autorización. |
| Contexto de una conversación | Slack autorizado, con hilo y alcance | Resumir; no copiar canales ni tratar un resumen aislado como política. |

La tabla no autoriza a consultar una fuente con más permisos de los necesarios.
Si el acceso falla, la salida correcta es conservar la limitación y marcar el
hecho, no buscar una fuente paralela menos fiable.

## Separación de capas

La documentación mantiene separadas estas capas:

1. **Producto:** qué puede hacer el cliente y qué queda fuera.
2. **Workflow:** cómo entra una petición, qué decisiones toma y a qué sistema
   llama.
3. **Integraciones:** qué contrato tiene cada servicio y quién es su fuente de
   verdad.
4. **Observabilidad:** qué mide el dashboard, cómo lo agrega y qué no demuestra.
5. **Operación:** cómo se diagnostica, prueba, aprueba y revierte un cambio.
6. **Publicación:** cómo se indexa, se renderiza y se conserva la ruta.

Mezclar estas capas produce errores frecuentes: declarar que una integración
está disponible porque aparece en la interfaz, llamar producción a un plan,
confundir un label con un resultado o cambiar un workflow desde una tarea de
documentación.

## Resultado esperado

Una actualización correcta deja un lector capaz de:

* encontrar la página desde el índice del dominio;
* entender el recorrido principal y sus excepciones;
* saber qué sistema confirma el resultado;
* distinguir lo observado de lo propuesto;
* localizar la fuente propietaria y la siguiente validación;
* repetir las comprobaciones sin exponer información sensible.

La aplicación paso a paso está en [Documentar en este repositorio](/method/how-to/documentation).
Las reglas mínimas están en [Prácticas obligatorias](/method/reference/best-practices) y
la comprobación final en [Validar una publicación](/method/how-to/publish).