ADR-080: Help content sync
Estado
Accepted — 2026-08-23
Contexto
IVPrior (ADR-045) trata Help como parte del producto: ninguna UI S-xxx se cierra sin artículo, registry e imagen en el mismo PR. IVPrior ya tiene apps/help (ADR-079) pero el sync estaba diferido. Sin gate, el desfase pantalla↔artículo se repite.
Decisión
Todo cambio que entrega o modifica una experiencia visible al usuario (S-xxx, copy operativo) MUST incluir Help en el mismo PR/slice, salvo excepciones abajo.
Mismo patrón IVPrior. Adaptaciones IVPrior:
- Copy Help EN + ES, misma sustancia (ADR-035). Un locale stub no cumple el gate.
- Artículos en
apps/help/content/{en,es}/{module}/{slug}.md(Markdown). MDX cuando haya componentes. - Registry:
apps/web/lib/screen-help-map.ts. - Gate:
pnpm --filter @ivprior/web test(help-content-sync). - Icono ? contextual: mismo slice que la primera pantalla P0 que lo necesite; el registry se llena desde ya.
Entregables por pantalla
- Artículo EN y ES con barra de calidad (
.specify/memory/help-content.md). - Entrada en
SCREEN_HELP_MAP+ patrón de ruta cuando exista URL. - Imagen en
apps/help/public/help/{screen-id}/. - Smoke:
resolveContextualHelpUrl→ artículo (cuando el header?exista). - Test del lector: un finance manager entiende KPIs/columnas/estados sin preguntar.
Excepciones
- Infra / DX / CI sin UI.
- Refactor interno invisible.
- API sin pantalla ni copy user-facing.
- Spikes y briefs.
SDLC
| Herramienta | Gate |
|---|---|
/speckit.tasks | Fase Help content si hay S-xxx |
/opsx:propose | Sección Help en tasks.md si apps/web / apps/help |
/opsx:apply | No marcar UI [x] sin Help |
/opsx:archive · /cierre-session | Checklist .specify/checklists/help-content.md |
Developer Docs (allowlist, OpenAPI, DX) es el paralelo contributor: .specify/memory/dev-docs-content.md.
Consecuencias
- Primer slice UI P0 (p. ej. S-001) MUST traer artículo + registry + imagen.
- Mapa vacío es válido hasta que exista la primera pantalla mapeada.