¿Qué hace docs-update?
La documentación se oxida en silencio: nada falla, el texto simplemente deja de ser verdad. Este skill encuentra la documentación que los cambios recientes deberían haber tocado y la pone al día.
Los comandos a continuación escriben ~/.claude/skills/docs-update/scripts/ completo. Ejecútalos
tal como están escritos: conserva la ~ inicial y no la expandas. Una
regla de permiso coincide con la cadena de comando literal, por lo que /home/<tu>/.claude/...
(la tilde expandida), python3 ~/..., una ruta relativa y un cd primero son cada una
una cadena diferente, y cada una vuelve a solicitar permiso. Una ruta con tilde no es "la ruta absoluta
escrita de manera informal" – para una regla de permiso es la ruta.
La documentación viaja con el cambio, no después. Si estás en una rama de funcionalidad, confirma la documentación en esa rama para que la fusión la lleve consigo. Un PR de documentación posterior es un PR de documentación que nadie escribe.
1. Elegir el alcance
En orden de precedencia:
El usuario lo dijo. "barrido completo", "desde v2.1", "solo esta rama" – úsalo.
Un barrido completo es --full y lo lee todo; es la opción correcta después de un
largo período sin cambios o al adoptar este skill en un repositorio por primera vez.
Un documento registra su propio punto de última actualización:
~/.claude/skills/docs-update/scripts/docscheck.py markers
Si un documento lleva Última actualización: <fecha|commit>, limita ese documento desde allí
(--since). Los documentos que discrepan tienen sus propios alcances; no hay una única respuesta.
De lo contrario, se deriva de git:
~/.claude/skills/docs-update/scripts/docscheck.py scope
Prefiere la última rama fusionada (el trabajo de una rama es la unidad que la gente
quiere decir), retrocediendo al último commit. Sobrescribe con --since <ref>.
El trabajo realizado en esta sesión es el caso que el script no puede ver. Si esta sesión
realizó los cambios, ya conoces los archivos; pasa la referencia previa a la sesión como
--since, o trabaja a partir de tu propia lista de ediciones.
scope separa kind=code de kind=doc-already-touched. La segunda lista
importa: esos documentos se actualizaron junto con el cambio, así que verifícalos por
corrección en lugar de por ausencia.
2. Encontrar la documentación que el cambio realmente alcanza
~/.claude/skills/docs-update/scripts/docscheck.py impacted
Para cada archivo de código modificado, esto informa los documentos que mencionan esa ruta exacta. Un documento que cita un archivo que modificaste es el documento con mayor probabilidad de estar describiendo algo que ya no es cierto, y es un punto de partida mucho mejor que releer cada documento.
Coincide solo con rutas completas, deliberadamente. Coincidir también con directorios padre
suena más generoso y es inútil: en un monorepositorio apps/web-nuxt/ aparece en 55
de 62 documentos, por lo que todo impacta todo.
result=none es normal y no significa "nada que hacer" – significa que ningún documento menciona
estas rutas, así que juzga por tema en su lugar. Que es el paso 3.
3. Juzgar por tema, usando la taxonomía de documentación del propio repositorio
impacted encuentra citas de rutas. No puede encontrar un documento que describa un comportamiento
que cambiaste sin nombrar un archivo. Así que lee el cambio y pregunta qué significa.
Primero aprende cómo este repositorio organiza la documentación – un brain/, un docs/, un CONTEXT.md,
un directorio ADR – y sigue esa estructura en lugar de inventar una. Si un
skill de proyecto cubre documentación (.claude/skills/*), prevalece sobre este.
El mapeo habitual:
| El cambio | El documento |
|---|---|
| nueva funcionalidad visible para el usuario | documento de la funcionalidad + su fila en el índice/catálogo; lista de funcionalidades en el README |
| cambio de comportamiento existente | el documento de esa funcionalidad |
| esquema, autenticación, compilación, almacenamiento, tiempo real, proveedores | el documento de arquitectura correspondiente |
| una decisión no obvia, o una surgida en la revisión | el registro de decisiones/ADR, con su porqué |
| nuevo término | el glosario |
| variable de entorno, comando o script nuevo o modificado | README y cualquier documento de configuración/operaciones |
| nueva dependencia | cualquier documento de lista de pila técnica (se mantienen a mano y siempre se olvidan – compara el manifiesto) |
| cambio visible para el usuario | CHANGELOG [No publicado] |
Dos trampas:
- Hechos derivados incrustados en prosa. Un documento que dice "la versión actual es 2.16.2" o enumera la pila técnica es una copia de otra cosa que se movió. Compara la fuente de verdad (el manifiesto, el archivo de versión) en lugar de confiar en la prosa.
- Documentos que están destinados a ser históricos o aspiracionales. Las entradas de CHANGELOG, TODO y ROADMAP citan archivos que fueron eliminados o nunca escritos. No los "arregles".
4. Verificar que las citas aún se resuelven
~/.claude/skills/docs-update/scripts/docscheck.py links
Dos tipos:
kind=link– un enlace relativo en markdown cuyo destino ha desaparecido. Siempre es un problema real.kind=source– una ruta en código en línea que ya no existe, generalmente porque el archivo se movió o renombró. Los documentos narrativos están excluidos, y las expansiones de llaves,<placeholders>, globs y la salida de compilación ignorada por git se filtran, por lo que lo que sobrevive vale la pena revisarlo.
Arregla lo que está dentro del alcance. Los hallazgos en otras partes del repositorio vale la pena reportarlos, pero no amplíes silenciosamente el trabajo a un barrido completo.
5. Escribir
Deslopea todo lo que escribes
Aplica el skill unslop a cada línea que agregues o modifiques. La documentación es
donde el slop causa más daño: la leen personas que intentan aprender algo,
es lo primero que encuentra un recién llegado y, a diferencia de un mensaje de chat, permanece.
Las señales que aparecen específicamente en la documentación:
- Aperturas para despejar la garganta. "Este documento proporciona una visión general de...", "En esta sección exploraremos...". Bórralas y comienza con el hecho.
- Repetir el código en prosa. "La función
getUserobtiene un usuario." Si la oración es el identificador expandido al inglés, no vale nada. Escribe la parte que el código no puede decir: la restricción, el porqué, el problema. - Intensificadores vacíos: integral, robusto, sin fisuras, potente, flexible, simplemente, fácilmente, solo. "Simplemente ejecuta X" es falso siempre que X no sea simple.
- Ambigüedades cuando la respuesta es definitiva: "generalmente", "típicamente", "debería normalmente". O lo hace o depende de algo que se pueda nombrar – nómbralo.
- Relleno de nota-que: "Es importante tener en cuenta que", "Ten en cuenta", "Mantén en mente". La oración después es el contenido; públicalo.
- Secciones de resumen que resumen la página anterior. Si el documento necesita un resumen, es demasiado largo.
- Columnas de descripción que repiten el nombre. Una fila de tabla
| --verbose | Habilita la salida detallada |cuesta una línea y no enseña nada. - Relleno de regla de tres: un tercer ejemplo agregado por ritmo en lugar de porque difiere de los dos primeros.
Coincide con el archivo, no con el slop
Coincide con la voz existente del archivo: su tiempo verbal, su densidad, si las entradas son de una línea o en prosa. Un documento en el que una sección de repente se lee diferente es peor que uno que es uniformemente conciso.
Estas dos reglas solo chocan cuando el documento existente es en sí mismo descuidado. Entonces: coincide con su estructura y densidad, no con su relleno, y no reescribas secciones que no hayas tocado de otra manera. Una actualización de documentación que también reestiliza todo el archivo es un diff no revisable y entierra el cambio que realmente importaba. Si un documento necesita una revisión de prosa completa, dilo y ofrécelo como un trabajo aparte.
El resto
- Enlaza las rutas de origen en lugar de repetir el código, para que el próximo cambio rompa el enlace en lugar de contradecir silenciosamente la prosa.
- Describe lo que es verdad ahora, en tiempo presente. Los documentos no son un changelog: "reemplazamos X por Y" pertenece al CHANGELOG, "el sistema usa Y" al documento.
- Si un documento tiene un marcador de última actualización, muévelo.
6. Informar
- el alcance utilizado y por qué ese
- documentos actualizados y qué cambió en cada uno
- documentos revisados y deliberadamente dejados como están
- enlaces rotos o citas encontradas fuera del alcance, listadas pero no corregidas
- cualquier cosa que no hayas podido juzgar sin el usuario