# Regla: Analizar la estructura de directorios antes de escribir documentación o MDs

Esta regla es OBLIGATORIA y aplica cada vez que Claude va a **crear un
directorio nuevo** o **escribir un archivo de documentación** (`.md`, `.json`
de reporte, informe, ADR, plan, análisis, output de auditoría/diseño/research)
en cualquier proyecto del usuario.

Cierra un patrón conductual recurrente: el agente escribe un documento en un
directorio nuevo elegido ad-hoc — en idioma o nombre distinto al que el
proyecto ya usa para ese dominio — y produce **directorios paralelos
divergentes** que fragmentan la memoria institucional.

---

## Principio

> Antes de crear un directorio nuevo o escribir un MD/reporte, **analiza
> primero la estructura de directorios existente** (`Glob`/`ls`) para
> descubrir la convención que el proyecto YA usa para ese dominio, y
> **reúsala**. NUNCA crees un directorio paralelo para un dominio que ya
> tiene uno. Solo cuando no exista precedente, crea uno nuevo siguiendo la
> convención dominante del proyecto; como desempate del **nombre**, prefiere
> español de México — salvo que exista un path canónico establecido (aunque
> sea en inglés), en cuyo caso ese path gana.

El costo de un `ls` antes de escribir es de 1 segundo. El costo de un
directorio paralelo es: referencias colgadas, búsquedas que fallan, memoria
institucional partida, y una sesión futura de depuración/unificación.

---

## Cuándo aplicar

OBLIGATORIO antes de:

- Escribir un reporte de auditoría, verificación, nemesis, revisión, análisis.
- Escribir un documento de diseño/UX (propuesta, tokens, discovery, UI-SPEC).
- Crear un ADR, plan, spec, runbook, research output.
- Crear cualquier directorio nuevo bajo `.planning/`, `docs/`, o equivalente.
- Persistir cualquier `.md`/`.json` que sea memoria del proyecto (no código).

NO aplica cuando:

- El comando/agente/herramienta **fija un path canónico de output** — en ese
  caso úsalo tal cual, no lo cuestiones (ej: un agente que pinea
  `.planning/audit/findings/iter-N/`).
- El archivo es código fuente (sigue las convenciones del lenguaje/framework).
- El usuario indicó explícitamente la ruta exacta donde escribir.
- Es un archivo efímero de scratch que se borrará en el mismo turno.

---

## Cómo aplicar — protocolo de 4 pasos

### Paso 1 — Listar la estructura existente

Antes de elegir dónde escribir:

```bash
ls .planning/          # o el directorio raíz de docs del proyecto
ls docs/
```

O con Glob: `**/{audit,auditoria,diseno*,ux,design,research,specs}/`.

### Paso 2 — Buscar si el dominio ya tiene directorio (incluye variantes es/en)

Pregúntate: ¿ya existe un directorio para este tipo de artefacto? Busca
**variantes en ambos idiomas** y sinónimos:

| Dominio | Variantes a buscar antes de crear |
|---|---|
| Auditoría | `audit/`, `auditoria/`, `auditorias/`, `findings/` |
| Diseño/UX | `diseno/`, `diseno-visual/`, `ux/`, `ui/`, `design/` |
| Investigación | `research/`, `investigacion/`, `knowledge/` |
| Decisiones | `adrs/`, `adr/`, `decisiones/` |
| Sesiones | `sessions/`, `sesiones/` |
| Deuda | `DEUDAS.md`, `DEUDA-TECNICA.md`, `deuda/`, `debt/` |

### Paso 3 — Decidir el destino

- **Si ya existe un directorio para el dominio** → escribe ahí. Punto. Aunque
  el nombre existente esté en el "idioma equivocado", reusarlo es superior a
  crear un paralelo. La consistencia gana sobre la preferencia de idioma.
- **Si existe un path canónico de la herramienta** (swl-ses pinea
  `.planning/audit/`, `knowledge/outputs/`, `sessions/`, etc.) → ese path es
  la fuente de verdad. NO lo dupliques en español.
- **Si NO existe precedente** → crea uno nuevo siguiendo la convención
  dominante del proyecto (mira cómo están nombrados los directorios hermanos).

### Paso 4 — Desempate del nombre (solo para directorios genuinamente nuevos)

Cuando creas un nombre nuevo sin precedente ni path canónico:

- Prefiere **español de México** (consistente con
  `~/.claude/rules/brevedad-output.md § Idioma obligatorio`): `diseno/`,
  `investigacion/`, `auditoria/` antes que `design/`, `research/`, `audit/`.
- **PERO**: si el proyecto ya tiene una convención de idioma dominante para
  sus directorios (ej: swl-ses usa mayormente inglés: `audit/`, `knowledge/`,
  `sessions/`, `research/`), respeta ESA convención sobre la preferencia
  general — la coherencia intra-proyecto manda.
- Identificadores técnicos (nombres que un comando/script consume como string)
  siguen la convención del consumidor, no la preferencia de idioma.

---

## La tensión es/en — cómo resolverla (no es "español siempre")

"Preferir español" es un **desempate**, no un mandato absoluto. La jerarquía
de decisión, de mayor a menor prioridad:

1. **Path canónico fijado por la herramienta** (gana siempre, aunque sea inglés).
2. **Directorio existente para el dominio** (reusar, aunque el idioma "no cuadre").
3. **Convención de idioma dominante del proyecto** (si el proyecto es es → es;
   si es en → en).
4. **Preferencia general español de México** (solo cuando 1-3 no aplican).

Renombrar un path canónico inglés establecido a español **viola** esta regla:
reintroduce divergencia en vez de eliminarla. El objetivo es UNA convención por
proyecto, no "todo en español".


---

## Eje técnico-runtime vs vocabulario-de-dominio (refina la jerarquía)

La jerarquía de arriba decide entre español e inglés *cuando todo el árbol usa
un solo idioma*. Pero muchos proyectos adoptan una convención **mixta por
categoría**: "identificadores técnicos en inglés, vocabulario de cara al usuario
en el idioma del proyecto" (caso swl-ses). Ahí, **clasifica el directorio ANTES**
de aplicar la jerarquía:

- **Path runtime/técnico → inglés.** Telemetría, estado interno, caches, logs
  archivados, outputs de tooling, índices. No los lee el usuario final; los
  consume el código como string. Ej. en swl-ses: `.planning/evolution/`,
  `.planning/auto-evolution/`, `.planning/user-profile/`, `.planning/archive/`,
  `.planning/traces/`, `.planning/sessions/`, `.planning/audit/`.
- **Vocabulario de dominio de cara al usuario → idioma del proyecto.** Artefactos
  acoplados a comandos/UX cuyo nombre el usuario lee y escribe. Ej. en swl-ses:
  `.planning/fases/` permanece **español** porque su comando es `/swl:planear-fase`
  (español, intocable). Cambiar el dir sin cambiar el comando crea una
  inconsistencia comando↔directorio *peor* que la divergencia que se quería evitar.

**Regla de coherencia comando↔directorio:** el nombre del data dir debe espejar
el idioma del comando que escribe en él. NUNCA partir un par comando↔directorio
en dos idiomas.

**Consolidar islas runtime SÍ es válido (no viola "no renombrar paths
establecidos"):** si un proyecto con convención técnico-inglés tiene islas
runtime en español (`evolucion/`, `archivo/`), alinearlas a inglés *reduce*
divergencia — es lo opuesto a "renombrar `audit/` a español". La prohibición de
renombrar aplica a mover *desde* la convención establecida, no *hacia* ella. Las
islas runtime alineadas requieren shim de migración (renombrar el dir físico en
proyectos que ya tienen datos) — ver `scripts/instalador.js § 6c-bis` en swl-ses.


---

## Anti-patrones explícitos

- **Crear `ux/` cuando ya existe `diseno-visual/`** (o viceversa) sin haber
  hecho `ls .planning/` primero. Caso real: SIGM acumuló ambos por sesiones
  distintas que no verificaron el precedente.
- **Crear `auditoria/` (es) cuando la herramienta pinea `audit/` (en)** como
  path canónico. Caso real: `/swl:verificar` y el consolidado de `/swl:nemesis`
  escribieron en `auditoria/` mientras los reportes por-router iban a
  `audit/findings/` — misma corrida, dos directorios.
- **Renombrar `audit/`, `knowledge/`, `sessions/` a español** "porque la
  preferencia es español". Eso rompe paths canónicos y reintroduce divergencia.
- **Escribir un reporte en un directorio top-level nuevo** sin revisar los
  directorios hermanos existentes.
- **Asumir que no hay precedente sin buscar variantes es/en** del nombre del
  dominio.

---

## Excepciones legítimas

NO aplicar (o aplicar con criterio reducido) cuando:

1. El comando/agente **pinea el path** — úsalo, no analices.
2. El usuario dictó la ruta exacta.
3. Es un archivo de scratch efímero del mismo turno.
4. Es el **primer** documento del proyecto (no hay estructura que analizar
   todavía) — ahí creas la convención; hazlo deliberadamente y en español si
   no hay restricción técnica.

---

## Checklist antes de escribir un MD/reporte o crear un directorio

- [ ] Ejecuté `ls`/`Glob` sobre el directorio raíz de docs (`.planning/`, `docs/`).
- [ ] Busqué variantes es/en del nombre del dominio (audit/auditoria,
      diseno/ux/design, research/investigacion).
- [ ] Si existe directorio para el dominio → escribo ahí (no creo paralelo).
- [ ] Si la herramienta pinea path canónico → uso ese (aunque sea inglés).
- [ ] Si creo uno nuevo → sigue la convención de idioma dominante del proyecto;
      español como desempate solo sin precedente ni path canónico.
- [ ] No reintroduje divergencia renombrando un path canónico establecido.

---

## Origen de esta regla

Sesión 2026-05-31, proyecto SIGM. Al depurar `.planning/` se detectaron **dos
pares de directorios divergentes** creados por sesiones distintas para el mismo
dominio, en idiomas distintos:

- `.planning/audit/` (en, canónico swl-ses) vs `.planning/auditoria/` (es,
  ad-hoc). La misma corrida de `/swl:nemesis` quedó partida entre ambos; 8
  documentos con referencias colgadas tras la consolidación.
- `.planning/ux/` (en, 2026-05-30) vs `.planning/diseno-visual/` (es,
  2026-05-11). La sesión 05-30 creó `ux/` sin verificar que `diseno-visual/`
  ya existía.

Causa raíz dual: (a) **conductual** — el agente no analiza la estructura
existente antes de escribir (esta regla); (b) **de herramienta** — varios
comandos/agentes de swl-ses no fijan path canónico de output (ticket
`DT-PLANNING-OUTPUT-PATHS` en swl-ses). Esta regla ataca el lado conductual y
aplica a todo proyecto del usuario, use o no swl-ses.

Relación con otras reglas:
- `~/.claude/rules/brevedad-output.md § Idioma obligatorio` — la preferencia
  español que esta regla usa como desempate.
- `~/.claude/rules/memoria-consolidada.md § no-duplicación` — un dato vive en
  un solo canal; esta regla extiende el principio a directorios.
- `~/.claude/rules/sin-duplicacion-reglas-globales.md` — analogía: no duplicar
  contenido que ya vive en su lugar canónico.
