@saulwade/swl-ses 2.4.2 → 2.5.1

package/reglas/analizar-directorios-antes-de-escribir.md

@@ -1,228 +1,47 @@
 # 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.
-
----
+Regla OBLIGATORIA antes de 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). Cierra el patrón de 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
+> primero la estructura existente** (`ls`/`Glob`) 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. El `ls` cuesta 1
+> segundo; el paralelo cuesta referencias colgadas y memoria partida.
 
-NO aplicar (o aplicar con criterio reducido) cuando:
+## Protocolo de 4 pasos
 
-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.
+1. **Listar** la estructura existente: `ls .planning/`, `ls docs/`, o Glob `**/{audit,auditoria,diseno*,ux,design,research,specs}/`.
+2. **Buscar** si el dominio ya tiene directorio en variantes es/en y sinónimos (audit/auditoria/findings, diseno/ux/design, research/investigacion/knowledge, adrs/decisiones, sessions/sesiones, deuda/debt).
+3. **Decidir**: directorio existente para el dominio → escribir ahí (aunque el idioma "no cuadre"); path canónico de la herramienta → usarlo tal cual, no duplicarlo en español; sin precedente → crear siguiendo la convención dominante del proyecto (mirar los directorios hermanos).
+4. **Desempate del nombre** (solo directorios genuinamente nuevos): español de México, salvo convención de idioma dominante del proyecto (la coherencia intra-proyecto manda) o identificador técnico cuya convención fija el consumidor.
 
----
+## Jerarquía de desempate es/en (mayor a menor prioridad)
 
-## Checklist antes de escribir un MD/reporte o crear un directorio
+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** (es → es; en → en).
+4. **Español de México** — solo cuando 1-3 no aplican. Renombrar un path canónico establecido a español VIOLA esta regla: el objetivo es UNA convención por proyecto, no "todo en español".
 
-- [ ] 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.
+## Eje técnico-runtime vs vocabulario-de-dominio
 
----
+- Clasificar ANTES de aplicar la jerarquía: paths runtime/técnicos (telemetría, caches, logs, outputs de tooling, índices) → inglés; vocabulario de cara al usuario (artefactos acoplados a comandos/UX) → idioma del proyecto.
+- NUNCA partir un par comando↔directorio en dos idiomas — el data dir espeja el idioma del comando que escribe en él. Consolidar islas runtime *hacia* la convención establecida SÍ es válido (con shim de migración si ya hay datos).
 
-## Origen de esta regla
+## Cuándo aplica y excepciones
 
-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:
+- Aplica antes de: reportes de auditoría/verificación/nemesis, docs de diseño/UX, ADRs, planes, specs, runbooks, cualquier `.md`/`.json` que sea memoria del proyecto (no código).
+- NO aplica: el comando/herramienta pinea el path canónico (úsalo sin cuestionar), el usuario dictó la ruta exacta, o es scratch efímero del mismo turno.
+- Primer documento del proyecto (sin estructura previa): ahí creas la convención — deliberadamente, en español si no hay restricción técnica.
 
-- `.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.
+## Anti-patrones
 
-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.
+- Crear `ux/` cuando ya existe `diseno-visual/` (o viceversa) sin `ls .planning/` previo.
+- Renombrar un path canónico establecido (`audit/`, `knowledge/`, `sessions/`) a español "porque la preferencia es español".
+- Asumir que no hay precedente sin buscar variantes es/en del nombre del dominio.
 
-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.
+Detalle extendido (tabla completa de variantes por dominio, jerarquía desarrollada, eje técnico-runtime con ejemplos swl-ses, casos reales SIGM, checklist y origen): `Skill("meta-reglas-extendido")` → `recursos/analizar-directorios-antes-de-escribir.md`.