# /documentar — Distribuir la conversacion en la documentacion del registry Documenta la **conversacion actual** repartiendo el contenido en TODOS los `.md` que correspondan: artefactos del registry (funciones, tipos, apps, projects, analysis, vaults) **y documentacion global del repo** (`docs/*`, `docs/adr/`, `CHANGELOG.md`, `dev/issues/*`, `.claude/rules/*`, `.claude/CLAUDE.md`, sub-CLAUDEs, READMEs/SPECs en apps). Cierra con una entrada en `/entrada_diario`. El objetivo es que **otro LLM (o yo en otra sesion) pueda continuar** sin haber visto la conversacion: contexto, decisiones, gotchas, paths, IDs, comandos exactos, "lo siguiente que pega". ## Uso ``` /documentar # documenta todo lo relevante de la sesion /documentar shaders_lab fase 6 # acota a artefactos/temas concretos (opcional) ``` `$ARGUMENTS` es opcional: si va vacio, documenta toda la sesion. Si lleva texto, usalo como hilo conductor para decidir que es relevante. --- ## Reglas duras 1. **NUNCA** escribir secretos en ningun `.md` ni en el diario: - Passwords, tokens, API keys, GPG keys, ssh private keys, valores reales de variables de entorno sensibles (`REGISTRY_API_TOKEN`, `*_SECRET`, `*_PASSWORD`, `*_TOKEN`, basicAuth en URLs). - Si el usuario lo pide explicitamente, OK. Por defecto, redactar como `` / `` o referenciar el origen (`pass entry registry_api`, `~/.fn_pc`). - URLs publicas, hosts, puertos, paths, IDs, nombres de servicios, env var **names** (no values), licencias, hashes de commit cortos: SI se documentan. 2. **NUNCA** sobreescribir secciones existentes ni reordenar contenido previo. Solo **append** o seccion nueva con timestamp/fase si encaja. 3. **SIEMPRE** consultar `registry.db` con FTS5 para encontrar el `.md` correcto antes de editar (no asumir paths). 4. **SIEMPRE** cerrar invocando `/entrada_diario` con un resumen del bloque (a no ser que el usuario diga lo contrario). 5. **Densidad util > prosa**: comandos exactos, IDs del registry, paths relativos, error messages literales, flags de build, decisiones (con el "porque"), bugs encontrados (con el fix), proximos pasos. Sin fluff. --- ## PASO 0 — Recopilar el material de la sesion Antes de escribir nada, repasar la conversacion y juntar: 1. **Artefactos tocados** (creados, editados, ejecutados, mencionados): - Funciones / tipos del registry → IDs `{name}_{lang}_{domain}`. - Apps (`apps/*` o `projects/*/apps/*`). - Projects (`projects/*`). - Analyses (`analysis/*` o `projects/*/analysis/*`). - Vaults (`projects/*/vaults/vault.yaml`). - Reglas (`.claude/rules/*.md`), ADRs (`docs/adr/*.md`), templates (`docs/templates/*`). - Issues (`dev/issues/*.md`, `dev/issues/completed/*.md`). - Docs globales (`docs/*.md`: architecture, integrity, execution_standard, fn_operations, sync_setup, init-pipelines, testing, functions, types, fn-registry-system-complete). - CLAUDE.md raiz (`.claude/CLAUDE.md`) y sub-CLAUDEs (`apps/*/.claude/CLAUDE.md`, `projects/*/apps/*/.claude/CLAUDE.md`, `analysis/*/.claude/CLAUDE.md`, `projects/*/analysis/*/.claude/CLAUDE.md`). - Docs sueltas en apps (`apps/*/SPEC.md`, `apps/*/README.md`, `apps/*/docs/*.md`, `cpp/DESIGN_SYSTEM.md`). - `CHANGELOG.md` raiz. 2. **Cambios concretos** desde git: ```bash cd /home/lucas/fn_registry git status --short git diff --stat git log --since="6 hours ago" --oneline ``` Cada path modificado mapea a un artefacto — convertir a su `.md`. 3. **Material no codigo** que vale la pena dejar registrado: - Decisiones de diseño y por que (anti-bitrot: el porque suele perderse). - Bugs encontrados + raiz + fix (no solo "fix"). - Atajos / convenciones nuevas. - Pendientes y "lo siguiente que pega" para la proxima sesion. - Aprendizajes operativos (build flags, cross-compile gotchas, env requerido). 4. **Filtrar secretos** segun la regla dura #1. Si el material es solo conversacion exploratoria sin artefactos tocados, ir directo a PASO 4 (solo diary). --- ## PASO 1 — Mapear cada bloque de informacion a su `.md` Para cada artefacto identificado, localizar su `.md` consultando `registry.db`: ```bash cd /home/lucas/fn_registry # Funcion / tipo sqlite3 registry.db "SELECT id, file_path FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'name:NAME* OR description:NAME*');" sqlite3 registry.db "SELECT id, file_path FROM types WHERE id IN (SELECT id FROM types_fts WHERE types_fts MATCH 'name:NAME* OR description:NAME*');" # App / project / analysis (los .md son nombres fijos) sqlite3 registry.db "SELECT id, dir_path FROM apps WHERE name = 'NAME';" # → {dir_path}/app.md sqlite3 registry.db "SELECT id, dir_path FROM projects WHERE name = 'NAME';" # → projects/NAME/project.md sqlite3 registry.db "SELECT id, dir_path FROM analysis WHERE name = 'NAME';" # → {dir_path}/analysis.md sqlite3 registry.db "SELECT id, name, path FROM vaults WHERE name = 'NAME';" # → vault.yaml entry ``` Si el `.md` aun no existe (artefacto recien creado en la sesion y todavia no indexado), el path se deduce de la convencion: - Funcion: `functions/{domain}/{name}.md`, `python/functions/{domain}/{name}.md`, `bash/functions/{domain}/{name}.md`, `frontend/functions/{domain}/{name}.md`, `cpp/functions/{domain}/{name}.md`. - Tipo: `types/{domain}/{name}.md` (codigo en `functions/{domain}/{name}.go`). - App: `apps/{name}/app.md` o `projects/{proyecto}/apps/{name}/app.md`. - Project: `projects/{name}/project.md`. - Analysis: `analysis/{name}/analysis.md` o `projects/{proyecto}/analysis/{name}/analysis.md`. ### Donde escribir dentro de cada `.md` | Tipo de `.md` | Seccion preferida para append | |-----------------------|----------------------------------------------------------------------------------------------------------------| | Funcion / tipo | `## Notas` al final. Si no existe, crearla. NO tocar el frontmatter salvo que el usuario pida cambiar metadata. | | App (`app.md`) | `## Estado actual` con sub-fases si el app ya las usa (ej. `### Fase 7 — ... [done]`). Si no, `## Notas`. Tambien `## Lo siguiente que pega` para futuros pasos. | | Project (`project.md`)| `## Notas` o seccion del area afectada (`## Apps`, `## Operacion`, `## Troubleshooting`). | | Analysis (`analysis.md`)| `## Notas` o `## Hallazgos` (crearla si no existe). | | Vault (`vault.yaml`) | Comentario al final del entry o crear `vaults/{name}/README.md` con notas operativas (NO meter datos sensibles). | | Regla (`.claude/rules/*`)| Solo si el usuario explicitamente formaliza una regla nueva — entonces archivo nuevo + entrada en `INDEX.md`. | | ADR (`docs/adr/*`) | Solo si la decision es arquitectural y persistente — archivo nuevo numerado. | ### Documentacion global / cross-cutting (NO saltarse) Estos `.md` describen el sistema entero, no un artefacto concreto. Cuando un cambio impacta convenciones, comportamiento de agentes, decisiones, issues abiertos o features visibles al usuario, **tambien** se actualizan aqui: | Archivo / carpeta | Cuando tocarlo | Como | |---------------------------------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| | `CHANGELOG.md` (raiz) | Cambio visible al usuario o agentes: nueva funcion/pipeline/app, breaking change, fix relevante, rename, deprecate. | Append bajo seccion del dia (`## YYYY-MM-DD`) con `### Added/Changed/Fixed/Removed/Deprecated`. NUNCA reescribir entradas previas. Si es trabajo en curso, usar `## [Unreleased]`. | | `docs/adr/NNNN-slug.md` | **Decision arquitectural** persistente con alternativas descartadas (no es regla operativa, es historia del por que). | Archivo nuevo numerado siguiendo plantilla en `docs/adr/README.md`. Estado inicial: `accepted` o `proposed`. | | `docs/architecture.md` | Cambia la arquitectura general (BDs, layers, flujo de datos, capas). | Append en seccion afectada o nueva subseccion. Mantener tablas y diagramas existentes. | | `docs/integrity.md` | Nueva regla de integridad / referencia cruzada que el indexer valida. | Append a la lista de reglas. Reflejar tambien en codigo del indexer si toca. | | `docs/execution_standard.md` | Cambia el estandar de ejecucion (`fn run`, despacho por lenguaje, env vars). | Append seccion. Sincronizar con `.claude/CLAUDE.md` si menciona los mismos comandos. | | `docs/sync_setup.md` | Cambia el flujo de `fn sync`, env vars (`FN_REGISTRY_API`, `REGISTRY_API_TOKEN`), `~/.fn_pc`, troubleshooting. | Append. Recordatorio: NO escribir el valor del token, solo el nombre. | | `docs/init-pipelines.md` | Nuevo pipeline de scaffolding o cambio en uno existente. | Append seccion del pipeline. | | `docs/testing.md` | Cambia convencion de tests, runners, layout de `*_test.go`/`test_*.py`. | Append seccion afectada. | | `docs/functions.md` / `docs/types.md` | Cambia el schema de la tabla `functions` o `types` (columnas, FTS5, enums, `params_schema`). | Append. Sincronizar con `.claude/CLAUDE.md` schema rapido. | | `docs/fn_operations.md` | Cambia el schema/comportamiento de `operations.db` o el bucle reactivo (entities, relations, executions, assertions). | Append seccion afectada. | | `docs/fn-registry-system-complete.md` | Snapshot completo del sistema — solo si la sesion implico un rediseño grande. Normalmente NO se toca por sesion. | Si toca, append seccion con timestamp. | | `docs/templates/*.md` | Cambia el frontmatter obligatorio de un tipo de artefacto (function/pipeline/component/type/app/project/analysis). | Editar la plantilla correspondiente. Tambien actualizar ejemplos en `.claude/CLAUDE.md`. | | `dev/issues/NNNN-*.md` | Sesion trabajo en un issue: progreso, blockers, decisiones del scope. | Append `## Notas / Progreso` con timestamp. NO mover de `dev/issues/` a `dev/issues/completed/` salvo que el issue cierre. | | `dev/issues/completed/NNNN-*.md` | Issue completado en esta sesion. | Mover el archivo a `completed/` (`git mv`) y actualizar la fila en `dev/issues/README.md` (estado `completado`, link a `completed/...`). | | `dev/issues/README.md` | Issue creado, cambia estado, prioridad, dependencias. | Editar la fila correspondiente o anadir nueva al final de la tabla. | | `.claude/rules/*.md` + `INDEX.md` | El usuario formaliza una nueva regla operativa. | Archivo nuevo + fila en `INDEX.md`. Numerar en el indice manteniendo orden. | | `.claude/CLAUDE.md` (raiz) | Cambio en convenciones globales del proyecto, comandos `fn` nuevos, env vars, estructura de carpetas, schema BDs. | Append en seccion afectada. Sincronizar con `docs/` si hay overlap. | | Sub-CLAUDE (`apps/*/.claude/CLAUDE.md`, `analysis/*/.claude/CLAUDE.md`, `projects/*/apps/*/.claude/CLAUDE.md`) | Cambio especifico en como un agente debe trabajar dentro de esa app/analysis (no global). | Append. NO duplicar reglas que ya estan en CLAUDE.md raiz. | | `cpp/DESIGN_SYSTEM.md` | Cambia tokens, layout, primitivas visuales del stack C++. | Append seccion afectada. | | `apps/*/SPEC.md`, `apps/*/README.md`, `apps/*/docs/*.md`, `apps/*/NEXT_STEPS_*.md` | App tiene docs propias mas alla de `app.md`. | Append. Si el contenido encaja mejor en `app.md`, preferir `app.md` y mencionar el SPEC desde ahi. | ### Reglas de decision rapidas - **¿Cambio visible / breaking / nueva feature?** → `CHANGELOG.md` SI. - **¿Decision con alternativas descartadas?** → ADR SI. Una regla operativa "haz X" sin alternativas → `.claude/rules/`. - **¿Cambia como un agente debe comportarse?** → `.claude/rules/` o `.claude/CLAUDE.md` (global) o sub-CLAUDE (local). - **¿Cambia el schema de BDs o columnas?** → `docs/functions.md`/`docs/types.md`/`docs/fn_operations.md` + `.claude/CLAUDE.md` schema rapido. - **¿Trabajo en un issue?** → `dev/issues/NNNN-*.md` + tabla en `dev/issues/README.md`. - **¿Cross-cutting sin artefacto y sin encajar arriba?** → solo diario (PASO 4). --- ## PASO 2 — Escribir las actualizaciones Para cada `.md` identificado: 1. `Read` el archivo para ver estructura actual y secciones. 2. Decidir si **append a seccion existente** o **crear seccion nueva**. 3. Usar `Edit` para append (preferible) o `Write` solo si es archivo nuevo. 4. **Mantener el estilo** del archivo (markdown, viñetas cortas, bloques de codigo con lenguaje). 5. **No tocar el frontmatter** salvo que el usuario haya cambiado metadata explicita (`description`, `tags`, `uses_functions`, `version`). Si se toca, re-indexar al final. ### Plantilla de bloque para append en `.md` de artefacto ```markdown ### {Fase / Tema corto} `[done|wip|notes]` {1-3 lineas de contexto: que se hizo y por que.} - Hecho: {cambio concreto, con path y/o ID si aplica}. - Hecho: {cambio concreto}. - Bug + fix: {sintoma → raiz → fix} (si procede). - Decision: {opcion elegida vs alternativa} — porque {razon} (si procede). - Pendiente: {algo que queda} (si procede). {Comando(s) exacto(s) si la operacion vale la pena reproducir.} ``` ### Plantilla para `## Lo siguiente que pega` (apps maduras) ```markdown - {Tarea proxima}: {contexto minimo, que tocar, criterio de hecho}. ``` --- ## PASO 3 — Reindexar si tocaste frontmatter o creaste artefacto Si los cambios de la sesion incluyen creacion de funciones/tipos/apps/projects/analysis/vaults o modificacion de frontmatter: ```bash cd /home/lucas/fn_registry && ./fn index ``` Y verificar: ```bash ./fn show {id_creado_o_modificado} ``` Si solo se editaron secciones de prosa (Notas, Estado actual, etc.) sin tocar frontmatter, el indexado igual recoge `documentation`/`notes` actualizados — re-indexar es barato y deja la BD coherente. --- ## PASO 4 — Cerrar con entrada al diario Invocar `/entrada_diario` con un resumen conciso de la sesion (3-6 viñetas, verbos en pasado para lo hecho, infinitivo para pendientes). Referenciar: - IDs de artefactos tocados. - Paths relativos clave. - Hashes de commit cortos si la sesion termino con commits. - ADRs / issues / proposals abiertos. Ejemplo de invocacion: ``` /entrada_diario shaders_lab fase 6 — menubar reusable (View + Layouts) cableado, persistencia de layouts en shaders_lab.db ``` Si el usuario ya invoco `/entrada_diario` antes en esta sesion para este bloque, **no duplicar**: solo añadir lo que no estaba. --- ## PASO 5 — Reportar al usuario Resumen breve (formato texto, no tabla a no ser que sean muchos): ``` === DOCUMENTADO === Artefactos (.md de registry): - apps/shaders_lab/app.md (Fase 6 — menubar) - cpp/functions/core/app_menubar.md (notas de uso) - cpp/functions/core/layouts_menu.md (notas de cableado) Globales: - CHANGELOG.md (Added: app_menubar, layouts_menu) - docs/adr/0002-menubar-arch.md (nuevo ADR — decision menubar reusable) - dev/issues/README.md (issue 0027 → completado) - dev/issues/completed/0027-...md (movido) - .claude/rules/cpp_icons.md (regla nueva, anadida a INDEX.md) Diario: docs/diary/2026-04-25.md (## 18:30 — ...) Re-indexado: si | no Pendientes registrados: {N} Secretos omitidos: {lista de tipos redactados, ej. "REGISTRY_API_TOKEN"} ``` --- ## Checklist final - [ ] Cada artefacto tocado tiene su `.md` actualizado (append, no overwrite). - [ ] Ningun secreto, password, token o key en los archivos. - [ ] Comandos exactos, IDs y paths para que otro LLM reproduzca. - [ ] Decisiones con su "porque", bugs con su raiz+fix. - [ ] `CHANGELOG.md` actualizado si el cambio es visible al usuario / agentes. - [ ] ADR creado (`docs/adr/NNNN-*.md`) si hay decision arquitectural con alternativas descartadas. - [ ] `dev/issues/*.md` y `dev/issues/README.md` actualizados si la sesion toco issues. - [ ] `docs/{architecture,integrity,functions,types,fn_operations,execution_standard,sync_setup,init-pipelines,testing}.md` actualizado si el cambio afecta lo que cada uno documenta. - [ ] `.claude/CLAUDE.md` raiz actualizado si cambian convenciones / comandos / schema globales. - [ ] `.claude/rules/*` + `INDEX.md` actualizado si el usuario formaliza una regla nueva. - [ ] Sub-CLAUDE de la app/analysis afectada actualizado si cambia comportamiento agente local. - [ ] `/entrada_diario` invocado con resumen de la sesion. - [ ] `./fn index` corrido si hubo creacion o cambio de frontmatter. - [ ] Reporte final al usuario con la lista de archivos tocados (artefactos + globales). $ARGUMENTS