| name | didactic-docs-style |
| description | Aplicá el contrato didáctico del repo al crear o revisar guías, READMEs y referencias de dynamic workflows, scaffolds o primitives, incluso cuando las produzca un workflow. |
Contrato de estilo para docs didácticas
Objetivo: hacer cada doc MÁS CLARO y MÁS DIDÁCTICO sin perder ni un bit de exactitud técnica; claridad y corrección
viajan juntas, nunca se intercambian. Este contrato es la fuente única del estándar de documentación didáctica del repo;
los workflows que editan o generan docs deben cargarlo y pasarlo a cada agente editor/reviewer.
En 30 segundos
Contrato único para que cada doc abra claro en media minuta, revele progresivamente y no sacrifique exactitud. Para
tono/🐼 en prosa, deferí a pandi-prose-style.
Shape mínimo de apertura: 2–3 frases → snippet ejecutable 3–8 líneas → referencia exhaustiva.
Las 8 reglas
- Apertura en 30 segundos. Empezá con 2-3 frases en lenguaje claro: qué es, qué problema resuelve y cuándo usarlo.
DESPUÉS poné un ejemplo mínimo ejecutable, ANTES de cualquier referencia exhaustiva.
- Disclosure progresivo. Orden: quickstart → conceptos → referencia → casos avanzados/bordes. Nunca abras con una
pared de detalles de API.
- Ayudas para decidir. Cuando la persona lectora deba elegir entre alternativas (agents vs pipeline vs parallel vs
race; run vs start; cuándo orquestar o no), agregá una tabla chica de decisión o un flowchart Mermaid. Preferí una
buena tabla a tres párrafos.
- Ejemplos mínimos. Cada primitive/comando lleva un snippet de 3-8 líneas que realmente podría correr. Verificá
firmas y comportamiento contra el código fuente de la extensión; nunca inventes.
- La exactitud es intocable. Cada afirmación debe poder chequearse en el código. Si dudás, leé la implementación.
Conservá todos los hechos existentes; podés reordenar, reescribir, ejemplificar e ilustrar, no debilitar ni eliminar.
- Español por defecto para docs públicas. La documentación pública del repo se escribe en español por defecto.
Mantené inglés solo para nombres de API, comandos, flags, package names, literales, títulos externos y términos
técnicos canónicos cuando traducirlos reduzca claridad.
- Mantenelo ajustado. Didáctico ≠ más largo. Cortá redundancia; los docs de primitives deben ser breves (viajan en
el paquete npm): objetivo ≤ ~65 líneas cada uno.
- Higiene Markdown. GFM válido, jerarquía sensata de headings, fences de código con language tags y diagramas
Mermaid en bloques con el tag
mermaid. Debe pasar los defaults de markdownlint: sin trailing spaces, un solo H1 y
líneas en blanco alrededor de headings, listas y fences. Ajustá la prosa fuente a un máximo de 120 caracteres por
línea; MD013 exceptúa tablas y bloques de código. Pasá ejemplos indivisibles a un fence cuando envolverlos reduzca
legibilidad o exactitud.
Páginas de scaffolds: shape requerido
Cada página docs/scaffolds/<key>.md además sigue este orden de secciones (ver cualquier página existente, por ejemplo
docs/scaffolds/map-reduce.md):
# <key> → blurb quote → En 30 segundos → Cómo lanzarlo (comandos /workflow ejecutables) → Diagrama
(Mermaid derivado del código real) → Qué hace → Cuándo usarlo → Cómo funciona → Input y output →
Fases.
Cómo se aplica
- Generación:
.pi/workflows/scaffold-docs-html.js escribe las fuentes Markdown bajo docs/scaffolds/ y corre
npm run sync:docs:html (el mirror docs/html/ es GENERADO; nunca lo edites a mano).
- Mejora:
.pi/workflows/didactic-docs.js edita docs en paralelo bajo este contrato y luego corre un panel de review
adversarial (exactitud + didáctica) → fixes → verificación (markdownlint + reconversión HTML).
- Ambos workflows deben leer este archivo y
pandi-prose-style como contratos de estilo, no copias ad hoc.
