79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
## Reports: reportes de trabajo como artefacto local
|
|
|
|
Un **report** es el entregable escrito de una tarea no trivial: qué se hizo, cómo se verificó y qué quedó pendiente, en formato copiable de un vistazo. Sirve para conservar el resultado fuera del chat y compartirlo rápido pasando la ruta del archivo.
|
|
|
|
Un report es un **artefacto** (ver `artefactos.md`), no documentación del registry. En consecuencia:
|
|
|
|
- **NO se versiona en el git del padre `fn_registry`** ni en ningún sub-repo: `reports/*` está en el `.gitignore` (solo el marcador `reports/.gitkeep` se versiona). Igual que los **vaults**.
|
|
- **NO sube a Gitea**: 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`.
|
|
- **NO se indexa en `registry.db`**: no hay tabla `reports` ni schema. KISS — son texto plano efímero, como los `playgrounds`.
|
|
|
|
### Qué NO es un report
|
|
|
|
| Es | Va a |
|
|
|---|---|
|
|
| Decisión de diseño (qué se decidió y por qué) | `docs/adr/` (versionado) |
|
|
| Norma operativa / convención | `.claude/rules/` (versionado) |
|
|
| Bitácora cronológica libre | `docs/diary/` (versionado) |
|
|
| **Resultado de una tarea concreta + su evidencia** | **`reports/` (artefacto local, NO versionado)** |
|
|
|
|
Si durante el trabajo aparece una decisión de diseño, esa decisión va a `docs/adr/` y el report solo la referencia.
|
|
|
|
### Ubicación
|
|
|
|
Como cualquier artefacto, un report puede vivir en dos sitios:
|
|
|
|
| Ubicación | Para qué |
|
|
|---|---|
|
|
| `reports/` (raíz) | Reportes que no pertenecen a ningún proyecto |
|
|
| `projects/<p>/reports/` | Reportes del trabajo de un proyecto concreto |
|
|
|
|
Ambas rutas están gitignored (`reports/*`, `projects/*/reports/`). Se pueden crear subcarpetas bajo `reports/` para agrupar (`reports/browser/`, `reports/audits/`, …).
|
|
|
|
### Convención de nombre
|
|
|
|
```
|
|
NNNN-YYYY-MM-DD-slug-corto.md
|
|
```
|
|
|
|
- `NNNN` — número incremental de 4 dígitos por carpeta (0001, 0002, …). Referencia corta ("report 0003").
|
|
- `YYYY-MM-DD` — fecha del trabajo (ISO en el nombre; en el cuerpo, fechas en formato europeo DD/MM/AAAA).
|
|
- `slug-corto` — kebab-case descriptivo. Ej: `browser-domain-audit-fixes`.
|
|
|
|
### Plantilla mínima
|
|
|
|
```markdown
|
|
# Report NNNN — Título
|
|
|
|
- **Fecha:** DD/MM/AAAA
|
|
- **Autor:** (agente/humano)
|
|
- **Ámbito:** (dominio/app/módulo tocado)
|
|
- **Estado:** done | parcial | bloqueado
|
|
|
|
## Resumen
|
|
Qué se hizo y el resultado, en 2-4 líneas.
|
|
|
|
## Cambios
|
|
Tabla o lista de lo tocado/creado, con el porqué.
|
|
|
|
## Verificación
|
|
Comandos ejecutados + salida cruda (build/test/vet/e2e). Sin "verde" sin evidencia.
|
|
|
|
## Gaps / pendientes
|
|
Lo que NO se cubrió y por qué (honesto: requiere Chrome, scope, etc.).
|
|
```
|
|
|
|
### Reglas
|
|
|
|
- **Cuándo escribir uno**: auditorías, tandas de fixes con verificación, refactors, investigaciones — cualquier trabajo cuyo resumen pedirías "para compartir rápido". Un fix de una línea NO necesita report; basta el commit.
|
|
- **Evidencia ejecutable obligatoria**: cada "pasa" lleva su comando/salida. Nada de smoke "no petó". Alineado con `dod_quality.md`.
|
|
- **Honestidad sobre gaps**: declarar siempre qué quedó sin cubrir.
|
|
- **Índice opcional**: si una carpeta de reports acumula muchos, mantener un `INDEX.md` local (también gitignored) ayuda a navegar; no es obligatorio.
|
|
|
|
### Relación con otras reglas y ADRs
|
|
|
|
- [[artefactos]] — report es un tipo de artefacto (no código reutilizable, ciclo de vida propio).
|
|
- [[playgrounds]] — mismo espíritu (artefacto local no indexado); el playground es prototipo de código, el report es resultado escrito.
|
|
- [[dod_quality]] — los reports heredan su exigencia de evidencia + gaps.
|
|
- ADR 0006 (`docs/adr/0006-reports-folder.md`) — decisión que crea la carpeta `reports/`.
|