pedroknigge/documentation-manager

Documentation Manager

Conocimiento vivo de proyecto para humanos y agentes de IA. El código es la fuente de verdad para el cómo y para si una afirmación es verdadera. AGENTS.md + docs/ capturan el qué, el por qué, las decisiones y los planes, pero nunca anulan el código cuando están en desacuerdo.

Reglas fundamentales

1. Preferir AGENTS.md como el centro. Si agents.md ya existe, usarlo. Si solo existe CLAUDE.md, extenderlo con un índice de documentos o agregar AGENTS.md y vincularlo cruzadamente; no crear tres centros en competencia.
2. Cada documento generado/actualizado debe usar enlaces Markdown relativos que apunten al centro y a los documentos relacionados.
3. Nunca eliminar conocimiento duradero sin una razón; prefijar notas de Sustituido por en las ADR.
4. No hacer auto-commit ni auto-push. Dejar git al usuario.
5. Escribir el contenido generado en el idioma del usuario (o el idioma dominante del repositorio). El cuerpo de esta habilidad está en inglés por compatibilidad con el ecosistema.
6. Priorizar la precisión y la utilidad sobre el volumen. Primero el conjunto principal; documentos opcionales bajo demanda.
7. Primero la intención (a nivel de proyecto). Clasificar la Intención: integrate | audit | from-zero (e híbrido opcional). Ver Paso 0. No es obligatorio para tareas puramente de feature/plan/sincronización.
8. El código manda en caso de conflicto. Las afirmaciones documentales que fallen la verificación estructural se marcan como Contradichas/Faltantes — no inventar código para que coincida con los documentos; corregir o marcar el documento.
9. Integrar primero (cuando Intención=integrate). Documentos maduros → índice + brechas + enlaces canónicos; sin reescritura paralela de visión-de-producto/requisitos/ADRs. Ver adopt-integrate.
10. Una autoridad por tema. Cada tema tiene un documento canónico; todo lo demás enlaza a él.
11. Matriz de cobertura en proyecto adopt/from-zero. Las superficies de producto (nav, ModuleId, paquete) aparecen como documentadas / enlazadas / brecha.
12. Atomicidad de features. Un slug ≈ un ModuleId o contexto acotado. Clústeres = índice + hijos.
13. Taxonomía de estados. references/status-taxonomy.md.
14. Sandbox opt-in / from-zero de primera clase. Out: sandbox:path cuando el usuario lo pide (test/, etc.). Los centros de sandbox muestran banner de no-SSOT + plan de promoción.
15. Piloto automático de features (v1.5 / v2). Simplemente "nueva feature X" / "documentá X" → la habilidad elige plan vs pack de feature, aplica no-escrituras por defecto, establece el Kind (nueva feature | spike | épica | rediseño). Puente de implementación (ubicación / stubs) solo con opt-in ("implementá", "stubs", "scaffold") — por defecto solo documentación + una sugerencia de una línea. Ver modes.md §3 y implementation-bridge.md.
16. Modo Plan (v1.3+). Las ideas de features en campo verde se ubican en docs/plans/<slug>/, no en un pack de implementación falso ni en un arranque completo de proyecto. Promover a docs/features/<slug>/ cuando el código sea real (no solo stubs).
17. Puente ArkGate (v1.4). Si se detecta ArkGate (ark.config.json, ark-check, .ark/, habilidades Ark) o el usuario acaba de pasar una puerta, ejecutar el subflujo puente: enriquecer el inventario desde el contrato; después de pasar la puerta → sincronización / auditoría acotada; violaciones residuales → marcar afirmaciones como Contradichas/Parciales — nunca reescribir documentos para excusar una arquitectura rota. Sin Ark → no operación. Las sugerencias de ubicación en el puente de implementación reutilizan las capas de Ark cuando se detectan. Ver arkgate-bridge.md y modes.md §9.
18. Panel de conocimiento (v1.6). Vista HTML estática opcional de planes/features/afirmaciones (scripts/generate-docs-dashboard.sh → docs/audit/generated/dashboard.html). Markdown es SSOT; HTML es solo vista con gitignore. Ofrecer después de una auditoría una vez o ante la solicitud "dashboard". Ver knowledge-dashboard.md y modes.md §10.
19. Endurecimiento de la habilidad (v1.7). Mantenedores: ejecutar validate-skill.sh + test-skill-hardening.sh antes del lanzamiento. Agentes: detectar instalación/versión mediante skill-discovery.md; sugerir reinstalación cuando esté desactualizada (sin parche automático silencioso).
20. Paquete v2.0. Completa la línea 10×: capacidades 1.4–1.7 más seguimiento de docs/adoption-matrix.md. El piso de instalación base sigue siendo 2.0.0; poliglota 2.1.0; monorepo 2.2.0; equipo 2.3.0; Bridge completo 2.4.0; la línea actual es 2.5.0+ (Knowledge OS primer incremento hacia 100× — afirmaciones vivas + auditoría CI; no es un segundo 10×).
21. Detección de stack poliglota (v2.1 Slice A / skill 2.1.0). Al descubrir proyecto (integrate / audit / from-zero / adopt), detectar el stack desde el sistema de archivos (package.json, pyproject.toml, go.mod, …) mediante skill-discovery.md Detección de stack poliglota (o scripts/detect-stack.sh). Usar Inventario por stack y Guía de diseño de documentos por stack — no asumir Node/TS. Nunca inventar ModuleIds/endpoints para frameworks sin evidencia de código. Ver modes.md §0.3.
22. Centros monorepo (v2.2 Slice B). Detectar árboles multi-paquete (pnpm-workspace.yaml, workspaces en package.json, go.work, directorios multi-paquete) mediante skill-discovery.md Centros monorepo (o scripts/detect-packages.sh). El centro raíz es un mapa + Índice de paquetes, no un volcado; la cobertura multi-paquete marca paquetes como brecha; por defecto no-escrituras de paquete cuando solo se indexa la raíz. Ver modes.md §0.4.
23. Gobernanza de equipo (v2.3 Slice C). docs/team/ opcional con propietarios + notas de aprobación (estilo última-aprobación). Crear vs enlazar según team-governance.md; el centro enlaza Team sin convertirse en una wiki de RRHH; integrar primero — agregar equipo no debe reescribir visión-de-producto / requisitos / ADRs. Sin motor CODEOWNERS ni BPM. Ver modes.md §11.
24. Telemetría de plantillas (v2.4 Slice D). Registro local opt-in solo para brechas de UX de plantilla/habilidad (template-telemetry.md; scripts/template-telemetry.sh). Desactivado por defecto; nunca enviar fuentes/secretos/URLs de repositorio; nunca a la red; sin operación en entornos aislados cuando el opt-in está desactivado. Ver modes.md §12.
25. Afirmaciones vivas + auditoría estructural CI (v2.5 / Knowledge OS primer incremento). Las matrices de auditoría usan afirmaciones vivas v0: anchor.path / opcional anchor.symbol / opcional anchor.hash, severity (critical | normal), veredictos sin cambios. Primero matriz (audit-template.md); procedimiento living-claims.md; cableado ADR-0001. Puntaje de verdad sigue siendo informativo (heurística del panel); local y aislado scripts/audit-claims.sh / ejemplo docs-audit CI es la puerta (fallar en Contradicho crítico). Sin SaaS. Ver modes.md §6 / §13.

Paso 0 — Detectar alcance, modo e Intención

Alcance (obligatorio):

Alcance	Cuándo	Enfoque de salida
project	Producto completo / "docs para el proyecto"	Centro + documentos del proyecto (según Intención)
feature	Feature/módulo nombrado con código (o pack de actualización)	docs/features/<slug>/ + enlace al centro
plan	Nueva feature/épica nombrada antes o sin código sólido	docs/plans/<slug>/ + enlace al centro
hybrid	Feature/plan cuando aún no hay centro	Pack o plan + centro mínimo

Modo (obligatorio):

Modo	Señales
bootstrap	Campo verde, sin centro/docs, o Intención from-zero en vacío/escaso
adopt	Código existe; documentos escasos/faltantes o Intención integrate
audit	"auditar docs", "docs vs código", desviación, validar afirmaciones
plan	"nueva feature", "plan", "épica", "vamos a construir X" sin código
feature	Documentar una feature/módulo que tiene (o es) código
sync	Diff / PR / actualizar documentos para un cambio; post-puerta cuando Ark acaba de pasar
roadmap	Planificar lanzamiento / actualizar lista de épicas

Intención (obligatoria solo para trabajo a nivel de proyecto):

Intención	Señales del usuario (ejemplos)	Comportamiento
integrate	"mejorar docs", "ordenar", "sync hub", mejora madura	adopt-integrate (o completo si escaso); pre-auditoría opcional si se sospecha desviación
audit	"auditar", "¿las docs mienten?", "docs vs código", "validar paths"	Inventario de código + matriz de afirmaciones solo (o luego entregar)
from-zero	"toda nueva", "de cero", "generá docs en test/", "full KB en carpeta X"	Base de conocimiento completa; preferir sandbox si se da una ruta; inferido del código; documentos antiguos = solo hipótesis

Inferencia (no preguntar de más):

• "nueva feature X" / "new feature X" / "quiero agregar X" → Piloto automático de features (plan si no hay código, feature si hay código; Kind según el tono). Intención = n/a
• "implementá X" / "generá stubs" / "scaffold X" → piloto automático Etapa A si es necesario + Puente de implementación opt-in (solo código si se pidieron stubs)
• "generá toda la documentación en test/" → Intención: from-zero | Out: sandbox:test/
• Repositorio maduro + "mejorá / integrá / indexá" → Intención: integrate
• "auditar docs" / "código vs docs" → Intención: audit
• Trabajo de proyecto ambiguo con docs/ existente → preguntar una vez: integrate | audit | from-zero
• Superficie única nombrada → nunca pedir al usuario que liste no-escrituras o elija carpetas
• "after ark-check" / "post-gate docs" / puerta acaba de ejecutarse + intención de docs → sync o audit con Puente ArkGate
• "dashboard" / "docs HTML" / "knowledge report" → generar Panel de conocimiento (knowledge-dashboard.md)
• "owners" / "quién es dueño" / "team docs" / "approval notes" / "docs/team" → Gobernanza de equipo (team-governance.md; modes §11)
• "template telemetry" / "opt-in telemetry" / "record template gap" → Telemetría de plantillas solo si el usuario opta (template-telemetry.md; modes §12); desactivado por defecto
• "living claims" / "truth score" / "docs CI" / "fail on Contradicted" → Afirmaciones vivas + puerta CI local (living-claims.md; modes §13)

Madurez (cuando sea relevante): escaso | mixto | maduro — ver modes.md.

Si el alcance/modo sigue siendo ambiguo después de la inferencia, preguntar una vez. Cargar procedimientos de references/modes.md.

Anunciar antes de escribir:

Alcance: <x> | Modo: <y> | Intención: <integrate|audit|from-zero|n/a> | Variante: <full|integrate|arkgate-bridge|n/a> | Madurez: <…|n/a> | Salida: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <sí|no|n/a> | ArkGate: <ninguno|detectado> | Slug: <slug|n/a>

Cuando integrate, listar no-escrituras (incluir no-escrituras de paquete cuando monorepo solo índice raíz). Cuando audit, listar ruta de matriz y principales contradicciones. Cuando from-zero + sandbox, incluir plan de promoción. Cuando plan o feature, listar ruta + no-escrituras por defecto. Cuando Puente ArkGate, listar señales y sincronización post-puerta vs auditoría-enriquecimiento. Cuando a nivel de proyecto, incluir Stack y Monorepo del descubrimiento.

Diseño recomendado

raíz-del-proyecto/
├── AGENTS.md
└── docs/
    ├── product-vision.md      # bootstrap / from-zero / adopt-full
    ├── requirements.md
    ├── architecture.md
    ├── roadmap.md
    ├── team/                  # v2.3 gobernanza de equipo (opcional)
    │   ├── OWNERS.md
    │   └── approval-notes.md
    ├── audit/                 # Intención audit (opcional)
    │   └── claims-matrix.md   # columnas afirmaciones vivas v0
    ├── adr/                   # ADR de paquete / proyecto (opcional)
    ├── plans/<slug>/          # v1.3 modo plan (pre-código / épica)
    │   └── README.md
    ├── decisions/
    └── features/<slug>/       # packs de feature respaldados por código

Documentos de soporte solo cuando estén justificados (excepto from-zero, que puede crear un conjunto mínimo completo).

Matriz de artefactos (resumen)

Artefacto	from-zero / bootstrap	integrate (maduro)	audit	plan	feature	sync
Centro	crear	extender / indexar	actualizar estado opcional	enlazar Plans	enlazar	si es necesario
Documentos narrativos principales	sí	no reescribir	no (solo lectura)	no	no	si hay impacto
Matriz de cobertura	sí	obligatorio	parte del inventario	fila opcional	fila	actualizar
Matriz de afirmaciones	opcional pre	recomendado si desviación	obligatorio	n/a	acotado si audit	si hay desviación
Planes docs/plans/	n/a	n/a	n/a	obligatorio	enlazar si existe	si hay impacto
Packs de feature	dominios clave	brechas / entradas	no (a menos que se pida)	no (hasta promover)	obligatorio	si hay impacto
Equipo docs/team/	si propietarios conocidos	crear/enlazar si se pide	no	n/a	n/a	si hay impacto
Árbol completo paralelo	sandbox ok	prohibido en raíz	n/a	n/a	n/a	n/a

Flujo de trabajo (todos los modos)

1. Paso 0 — alcance, modo, Intención (si proyecto), madurez/variante, Salida, slug; detectar señales de ArkGate cuando sea relevante; detectar Stack y Monorepo para trabajo de proyecto (skill-discovery.md Poliglota + Centros monorepo).
2. Descubrir código primero — inventario consciente del stack; si monorepo, Índice de paquetes + inventario por paquete; árbol, manifiestos, puntos de entrada, pruebas de muestra. Luego documentos (si los hay). Para features nombradas, buscar primero esa superficie. Si se detecta Ark, enriquecer inventario según arkgate-bridge.md.
3. Si audit o existen documentos y la Intención es integrate/from-zero con sospecha de desviación: ejecutar reconciliación (modes.md § Audit, audit-template.md). Post-puerta → transferencia puente (modes.md §9).
4. Planificar archivos — crear/actualizar y no-escrituras (valores por defecto para feature/plan).
5. ...

[truncado para traducción]