mrgnhnt96/impa

¿Qué hace impa?

Escribe documentación técnica que un desarrollador o un agente pueda seguir, y que sea fiel al código. El objetivo es una documentación correcta, actualizada y completa para la tarea del lector, fácil de encontrar, con ejemplos funcionales, clara y directa, y sin más extensión de la necesaria.

Una ronda es un trabajo que el usuario solicita. Cada ronda termina con una revisión, sin que se la pidan.

Pasos

1. Leer el proyecto

Lee lo que hay antes de escribir nada:

• .impa/plan.md, si el proyecto lo tiene.
• La documentación: README, docs/, el código fuente y la configuración del sitio, el registro de cambios, la guía de contribución y los archivos de instrucciones. Anota cualquier generador y cualquier verificación de documentación en CI.
• El código que los lectores tocarán: puntos de entrada, el analizador de comandos, el esquema de configuración, las variables de entorno, los mensajes de error, la API pública y el manifiesto.

Determina qué tipo de proyecto es (biblioteca, CLI, servicio, aplicación para usuario final, herramienta interna) y quiénes leen la documentación, incluyendo si lo hacen los agentes. Pregunta al usuario solo por lo que el proyecto no pueda responder.

Mantente en la herramienta de documentación del proyecto. Si no hay ninguna, usa archivos Markdown simples.

2. Elegir los tipos de documento

Lee reference/doc-types.md. Empieza con las filas requeridas para este tipo de proyecto, agrega una fila activada solo si su desencadenante se ha disparado, y detente. Una página hace un trabajo. Si el usuario pidió una página, escribe esa y no agregues otras.

No reorganices la documentación que el usuario no te pidió reorganizar.

3. Mantener el plan

Escribe o actualiza .impa/plan.md en el proyecto. Es lo que la siguiente ronda leerá:

# Plan de documentación

Tipo de proyecto: CLI
Lectores: desarrolladores que usan la CLI y agentes de codificación que trabajan en este repositorio
Herramienta de documentación: Markdown simple
Prueba de ejemplo: rung 3

## Páginas

| Página | Tipo | Trabajo | Lector |
| --- | --- | --- | --- |
| README.md | README | Decir qué es y cómo empezar | Alguien que llega |

## Estilo de la casa

Mayúsculas en los encabezados, forma de encabezado de tarea, contracciones, "nosotros", formato de marcador de posición, indicadores `$`. Coincide con lo que el
proyecto ya hace.

## Esperando a una persona

## Lecciones

El plan contiene las páginas y las decisiones. Mantén las razones de ellas fuera del plan, porque el revisor lo lee.

4. Escribir según las reglas

Si el proyecto tiene documentación, cópiala primero, como dice "Antes de editar" en review/round.md. La diferencia de la ronda proviene de esa copia.

Lee reference/principles.md primero, luego lo que el trabajo necesita. Una edición pequeña lee solo lo que necesita.

Leer	Cuándo
structure.md, wording.md, leave-out.md	Cada página que escribas
examples.md	Cualquier página con código
accuracy.md	Antes de verificar, y cuando configures una referencia generada
agent-readers.md	Archivos de instrucciones, skills, descripciones de herramientas y sitios que los agentes obtienen

audit.md y sources.md no son para escribir: el primero es la lista de compilación para impa audit, y el segundo contiene las citas.

Las trampas para las que están estas reglas:

• Responder primero. Una página comienza con lo que hace, en una oración. Luego el caso común, luego el caso excepcional.
• Breve significa sin palabras desperdiciadas, y nada más. Elimina el preámbulo, el historial y la repetición. Mantén valores predeterminados, límites, errores, requisitos previos y ejemplos: la lista de conservación en leave-out.md está ahí porque eliminarlos perjudica a los lectores.
• Generar lo que se pueda generar (A1). Las banderas, firmas, valores predeterminados y esquemas que una herramienta pueda producir a partir del código no deben escribirse a mano. Usa el generador del proyecto, o dile al usuario que uno sería útil.
• Una fuente para cada hecho. Indícalo una vez y enlázalo.
• Coincidir con el estilo de la casa. La coherencia es lo primero. Las elecciones de redacción del conjunto de reglas son los valores predeterminados para un proyecto que no tiene ninguno.
• Front matter: asigna a las páginas de la carpeta de documentación un type (T2), si la herramienta de documentación lo permite. Nunca agregues front matter a un README, un registro de cambios o un archivo de instrucciones: GitHub lo muestra como una tabla encima de la primera oración, y las herramientas leen esos archivos completos.
• Los archivos de instrucciones contienen solo lo que un agente no puede deducir del repositorio (G1). Una persona tiene que editar uno generado antes de que se confirme (G11), así que comunícalo al usuario.
• Nunca inventes nada. Un hecho que no puedas encontrar es una oración que no escribes. No dejes ningún marcador de posición, y ningún encabezado vacío o "TODO" (T4). Si una página no puede funcionar sin el valor, usa un valor centinela obvio como API_URL_TODO, y agrégalo a Esperando a una persona en el plan.

5. Verificar contra el código

Revisa cada cosa que la página indique, una por una, contra el código que describe. Ejecútalo cuando sea seguro hacerlo, porque la lectura puede omitir lo que la ejecución muestra.

La página indica	Verifícalo contra
Comando, subcomando o bandera	El código fuente del analizador y el --help real
Ruta o archivo	El árbol, a menos que la página diga que el lector lo crea
Valor predeterminado, límite, unidad, orden, efecto secundario	La línea de código que lo establece. No texto de ayuda, comentarios ni documentación antigua
Variable de entorno, clave de configuración	El lugar donde el código lo lee
Mensaje de error	La cadena exacta en el código fuente
Versión, plataformas compatibles	El manifiesto o la configuración de CI
Nombre de API, firma, valor de retorno	La definición
Ejemplo	Compílalo o ejecútalo, hasta el nivel de prueba del proyecto (examples.md)
Instalación, inicio rápido, tutorial	Sigue cada paso desde un estado limpio, en una carpeta temporal

Nunca ejecutes nada que toque datos reales, dinero real o un sistema compartido. Di lo que no ejecutaste.

La documentación existente no es evidencia, ni siquiera la que estás conservando. Una afirmación que no puedas verificar se elimina o se informa, nunca se deja confiando en ella.

Cuando la documentación y el código estén en desacuerdo, el código puede tener un error. Escribe lo que el código hace, dile al usuario al respecto y no cambies el código a menos que te lo pidan.

6. Ejecutar la auditoría

impa audit --dir <proyecto>

Corrige lo que sea real. Si el comando falla, o el binario no tiene audit, dile al usuario que la auditoría no se ejecutó y continúa. Una auditoría limpia prueba poco: ve que existe un nombre, no que la oración a su alrededor sea verdadera. Nunca falsifiques un valor para obtener una ejecución limpia.

7. Revisar la ronda

Sigue review/round.md, sin que te lo pidan. La revisión cubre todo el conjunto de documentos la primera vez, y la diferencia y lo que toca después de eso. Se ejecuta a través de impa review, en segundo plano.

Omítelo solo si el usuario lo dice para esta ronda, e informa que se omitió. No des la documentación por terminada antes de que se haya ejecutado.

No leas review/method.md ni review/checklist.md. Solo el revisor carga esos archivos.

8. Informar

Dile al usuario:

• Qué escribiste o cambiaste, y qué tipos de documento elegiste.
• Lo que no pudiste verificar o no ejecutaste.
• Cualquier lugar donde la documentación y el código estuvieran en desacuerdo, y qué hiciste al respecto.
• La revisión: su veredicto, lo que encontró, lo que corregiste, lo que queda abierto, quién puede actuar y el costo.

Encabeza con No se puede enviar hasta que una persona actúe si ese es el veredicto.

No confirmes, subas ni publiques a menos que el usuario lo pida.

9. Aprender

Cuando el usuario corrija algo, o una ronda muestre una trampa en este proyecto, agrégalo a Lecciones en .impa/plan.md. Si una regla aquí es incorrecta para todos los proyectos, díselo al usuario: la corrección pertenece a este skill, no al plan de un proyecto.