jimweller/documenter-plugin

Creación de documentación

Escribe contenido en markdown basado en el contexto actual de la conversación y el contenido de las carpetas.

README es la especificación del estado actual para un usuario humano, no un registro de cambios, no un registro de decisiones, no un registro histórico. Nunca registres información histórica o decisiones tomadas, solo la especificación tal como está en el momento de escribir el README.

Alcance

Encuentra todos los archivos README.md en el proyecto y actualiza cada uno. El contenido de las carpetas está al nivel del README y por debajo (hermanos y subcarpetas), nunca por encima (padres). Presta atención a las capas de las subcarpetas, el alcance y los contextos acotados. No filtres conceptos entre documentos en diferentes capas. Cada README cubre su propio nivel de directorio y por debajo, nunca preocupaciones de nivel superior.

Si el usuario proporcionó orientación específica o áreas de enfoque, aplica ese contexto al decidir qué enfatizar en la documentación.

Recopilar contexto

Nunca ejecutes git directamente. El script base que viene con este plugin cubre todo lo que esta habilidad necesita de git. Ejecuta cada comando desde la raíz del repositorio y escribe la ruta completa del script cada vez, porque las variables de shell no persisten entre comandos.

Comienza con el plan. Encuentra cada README, agrega un README raíz cuando no existe, resuelve la línea base de cada README, lista lo que ha cambiado desde esa línea base y dice qué hacer con cada README. Cuando la guía del usuario nombre directorios en los que enfocarse, pásalos después de readme. De lo contrario, no pases nada.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan readme [<focus-dir>...]

El plan imprime un bloque por acción.

• ## update nombra una línea base, un alcance y el README, seguido de los commits, el diff stat y el estado desde esa línea base. Pon el README al día. Un README que los cambios no afecten mantiene su contenido.
• ## new lista los README que se deben escribir a partir del código actual. No necesitan historial.
• ## unchanged y ## outside the focus listan los README que se deben dejar exactamente como están.

head none significa que el repositorio no tiene commits. Cada README es nuevo.

Para un bloque de actualización, cuenta los archivos en su stat. Con más de 20, omite el diff completo y lee los archivos modificados directamente. Con 20 o menos, lee el diff. Los archivos sin seguimiento, marcados ??, no aparecen en ningún diff, así que léelos directamente de cualquier manera. El alcance puede ser el alcance del bloque o un solo archivo, porque es un pathspec de git.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>

Luego, para cada README a actualizar o escribir, con alcance a su directorio:

1. Lee el README actual (si existe)

2. Explora el código base en ese nivel de directorio y por debajo

3. Revisa el historial de la conversación en busca de decisiones, cambios o lecciones aprendidas relevantes

4. Usa los cambios y el contexto de la conversación para identificar qué secciones necesitan actualización. Verifica el código contra la documentación y la documentación contra el código. Cuando el código elimina una función, bandera o módulo, busca grep en cada README su nombre, luego relee cada coincidencia y la descripción general de cada README en busca de una descripción en lenguaje sencillo de lo mismo.

   grep -rn '<nombre eliminado>' <dir>/README.md
   

Nunca incluyas la línea de marcador en el texto que escribas o edites. finish la agrega después de escribir. Al editar un README que ya termina con una, deja esa línea en paz.

Si nada cambió que justifique una actualización del README, dilo y continúa. finish aún se aplica.

Esquema de README.md

Orden de las secciones y contenido para un README.md. Cada sección se completa desde el proyecto de destino. Omite una sección para la que el proyecto no tenga nada.

• # Título y una descripción general de no más de cinco oraciones
• Imagen o video opcional
• ## Arquitectura - componentes como una lista con viñetas, cada uno con su propósito
• ## Prerrequisitos - cuentas, claves, credenciales, herramientas, entornos de ejecución, CLI, cada uno con la razón por la que se necesita
• ## Estructura del proyecto - solo carpetas, sin archivos, cada una con un propósito de una línea
• ## Instalación - los comandos que lo instalan
• ## Uso - los comandos que lo ejecutan
• ## Pruebas - omitido cuando el proyecto no tiene pruebas

Objetivo: menos de 500 líneas. Divide un README más largo moviendo los detalles a un README anidado junto al código que describe.

Forma

# Título

Breve descripción general. No más de cinco oraciones.

<!-- IMAGEN O VIDEO DESTACADO OPCIONAL -->
<img src="demo.png" alt="Demo" width="800"/>

## Arquitectura

Componentes de alto nivel y propósito

- Componente - propósito
- Componente - propósito

## Prerrequisitos

- Prerrequisito - descripción y razón (cuentas, claves, credenciales, herramientas, entornos de ejecución, CLI)

## Estructura del proyecto

Muestra la estructura de carpetas. No incluyas archivos.

```text
proyecto/
├── src/
│   ├── componente-a/     # propósito - ver src/componente-a/README.md
│   └── componente-b/     # propósito - ver src/componente-b/README.md
├── scripts/             # propósito
└── tests/               # propósito
```

## Instalación

```bash
# cómo se instala el proyecto
<comando de instalación>
```

## Uso

```bash
# cómo se ejecuta el proyecto
<comando de ejecución>
```

## Pruebas

```bash
# cómo se ejecutan las pruebas
<comando de prueba>
```

Finalizar

Ejecuta finish, cada vez, incluso en una ejecución que no haya escrito nada. plan dejó un archivo de plan atrás y solo finish lo elimina, por lo que una ejecución que omite finish deja un estado para que la siguiente lo encuentre.

bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish readme

Estampa cada README que el plan marcó como nuevo o actualizado, y cada README creado desde el plan, con el HEAD que el plan verificó. La estampa es una línea de marcador al final del README, un comentario HTML que nombra ese commit. finish deja intactos los README sin cambios y los README fuera del área de enfoque, y no estampa nada cuando el repositorio no tiene commits. El código de salida 4 significa que falta un README planificado. Escríbelo y ejecuta finish nuevamente.

• Nunca llames a stamp directamente y nunca escribas ni edites la línea de marcador manualmente. finish la escribe.
• El marcador son metadatos. La regla contra el registro del historial no se aplica a él.