dataforge/fn_registry
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity

chore: añadir slash command /documentar y entrada de diario 2026-04-25

Browse Source
This commit is contained in:
Egutierrez
2026-04-25 21:26:12 +02:00
parent 0db9242692
commit 2d35f5e1fb
2 changed files with 612 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/commands/documentar.md
+260
View File
@@ -0,0 +1,260 @@
# /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 `<token>` / `<password>` 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