fn_registry/docs/adr/0006-reports-folder.md

ADR 0006 — reports/ como artefacto local para reportes de trabajo

• Fecha: 2026-06-06
• Estado: accepted

Contexto

Cuando un agente termina una tarea no trivial (una auditoría, una tanda de fixes con verificación, un refactor, una investigación), el resumen ejecutable —qué se hizo, cómo se verificó, qué quedó pendiente— vivía solo en el chat de la sesión. Eso tiene tres problemas:

1. Se pierde: el chat no es consultable después; el resumen no queda en disco.
2. No es compartible rápido: para pasar el resultado hay que copiar a mano del chat.
3. No tiene formato estable: cada resumen sale distinto, sin garantía de evidencia ejecutable ni de declaración honesta de gaps.

Los contenedores existentes no encajan: los ADRs (docs/adr/) son decisiones de diseño; las reglas (.claude/rules/) son normas operativas; el diario (docs/diary/) es bitácora cronológica libre. Faltaba un sitio para el entregable de una tarea concreta: el resultado y su evidencia.

Punto clave de la decisión: un report no es documentación del registry, es un artefacto (en el sentido de .claude/rules/artefactos.md) — generado, con ciclo de vida propio, no código reutilizable. Y como artefacto del tipo "datos locales", se comporta como los vaults: no sube a Gitea ni se versiona en el git del padre.

Decisión

Crear la carpeta reports/ para reportes de trabajo, tratados como artefacto local:

1. No versionados, no Gitea. reports/* está en el .gitignore del padre (solo reports/.gitkeep se versiona, para mantener la carpeta presente). Un report no tiene repo propio: vive local en la máquina que lo generó. Compartir = pasar la ruta o copiar el contenido, no git push. Mismo trato que los vaults.
2. Conviven en raíz o en proyectos, como cualquier artefacto: reports/ (sueltos) o projects/<p>/reports/ (del trabajo de un proyecto). Ambas rutas gitignored (reports/*, projects/*/reports/). Se permiten subcarpetas para agrupar.
3. No se indexan en registry.db. Sin tabla reports ni schema (KISS) — son texto plano efímero, como los playgrounds.
4. Convención y plantilla viven en .claude/rules/reports.md (versionado): nombre NNNN-YYYY-MM-DD-slug.md, secciones Resumen/Cambios/Verificación/Gaps, evidencia ejecutable obligatoria.

Un report NO sustituye a un ADR ni a una regla: si durante el trabajo aparece una decisión de diseño, va a docs/adr/ y el report solo la referencia.

Alternativas consideradas

• Versionar los reports en el repo padre. Era el enfoque inicial de este ADR; descartado: un report es un artefacto (resultado de tarea, efímero, posiblemente voluminoso o ligado a un PC concreto), no documentación estable del registry. Versionarlos ensucia el historial del padre con entregables operativos. La convención correcta es la de los vaults: local, no Gitea.
• Dejar los resúmenes solo en el chat. Status quo; se pierden y no son compartibles. Es el motivo del ADR.
• Usar docs/diary/. El diario es cronológico, libre y versionado; mezclaría notas con entregables formales y no impone evidencia ejecutable.
• Un ADR por tarea. Sobrecarga el registro de decisiones con resultados operativos.
• Indexar los reports en registry.db. Añade schema y mantenimiento para un artefacto efímero. KISS: no se indexa, como los playgrounds.

Consecuencias

• .gitignore del padre gana reports/* (con !reports/.gitkeep) y projects/*/reports/.
• Nueva regla .claude/rules/reports.md con convención + plantilla; entrada en .claude/rules/INDEX.md.
• report se añade como tipo de artefacto en .claude/rules/artefactos.md (NO indexado, NO sub-repo Gitea).
• Mención en la sección "Estructura" / "Artefactos" de .claude/CLAUDE.md y en docs/README.md.
• Los agentes pueden escribir un report al cerrar una tarea no trivial y pasar la ruta para compartir, en vez de volcar el resumen al chat. El report queda local (no viaja por git/fn sync salvo que el usuario lo copie aparte).
• Primer report: projects/web_scraping/reports/0001-2026-06-06-browser-domain-audit-fixes.md (local, gitignored; vive en el proyecto porque el trabajo tocó sus apps). Cada project que use reports añade reports/* (salvo !reports/.gitkeep) a su propio .gitignore para no subirlos a su Gitea.

Relación con otras reglas y ADRs

• .claude/rules/artefactos.md — report es un tipo de artefacto; este ADR lo añade a la taxonomía.
• .claude/rules/reports.md — convención operativa derivada de este ADR.
• .claude/rules/playgrounds.md — mismo espíritu (artefacto local, no indexado).
• .claude/rules/dod_quality.md — los reports heredan su exigencia de evidencia ejecutable y gaps.
• ADR 0002 — apps/analyses SÍ son sub-repos Gitea; los reports NO (se parecen a los vaults, no a las apps).
• ADR 0005 — mantener el .git del padre ligero; no versionar reports refuerza esa línea.