Cuándo un hallazgo está equivocado
Una regla que se dispara con código correcto es un defecto de la regla, no algo que tu proyecto tenga que rodear. También lo es una regla que se quedó callada con código que debía atrapar, y una regla que tu asistente tenía enfrente y no siguió. Cada uno de esos se arregla una vez, en el toolkit, y todos los proyectos reciben el arreglo cuando el cambio del toolkit se publica.
Eso es lo que hace /improve-toolkit. No sirve para revisar tu propio código contra el analizador — eso es /review — y una advertencia no es un hallazgo equivocado: una advertencia es un caso que la regla no puede resolver sola, y decidirlo te toca a ti, como explica Leer un hallazgo.
Cómo reportarlo
Desde tu proyecto, dile a tu asistente qué pasó, con el archivo y la línea:
- El analizador marcó algo que es correcto: qué regla, en qué línea y por qué crees que el código está bien.
- El analizador dejó pasar algo que está mal: la línea, y la regla que esperabas que lo reportara.
- Tu asistente no siguió una regla: qué regla, y dónde la ignoró.
No hace falta que escribas /improve-toolkit; un reporte así lo arranca. El archivo y la línea importan más que la descripción, porque lo primero que hace es correr el analizador sobre ese archivo y mirar qué devuelve de verdad.
Necesita una copia del toolkit
El arreglo se escribe en el repositorio del toolkit, así que el comando tiene que encontrar una copia en tu computadora. Prueba la carpeta junto a tu proyecto, luego los lugares de siempre, y solo acepta una que de verdad sea el toolkit. Te dice la ruta que encontró y espera tu confirmación antes de escribir nada. Cuando encuentra varias, o ninguna, te pide la ruta en lugar de adivinar.
Lo que decide primero
¿Es el formateador? Cuando lo que reportaste es simplemente lo que produce el formateador del proyecto, no hay nada que arreglar: una regla escrita contra el formateador perdería en cada archivo. Deja por escrito la convención y se detiene.
Si no, pone el reporte en exactamente uno de cinco casos, con la evidencia que lo sostiene:
| Caso | Qué pasó | Qué se arregla |
|---|---|---|
| Falso negativo | El estándar ya lo prohíbe, una revisión podría probarlo desde el archivo y nada se reportó. | La revisión automática. |
| Falso positivo | Se marcó código correcto. | La revisión o la redacción de la regla, la que sea demasiado amplia. |
| Hueco del estándar | Ninguna regla cubre el caso. | Una regla nueva, con su revisión cuando un solo archivo basta para probarla. |
| Regla de criterio | La regla existe y es clara, no se siguió, y ninguna máquina que lee un archivo puede decidirla. | Nada todavía; mira abajo. |
| Hueco del flujo | La regla y su revisión están bien, pero nada las corrió. | El comando o el agente que debía hacerlo. |
Una regla de criterio detiene la corrida. Explica por qué se ignoró la regla y ofrece tres opciones: reforzar la redacción del estándar, reforzar el comando o el agente que debía aplicarla, o dejarla como está. Una regla que necesita criterio nunca se arregla con una revisión que adivina. Esas reglas son las de Lo que el analizador no puede revisar.
El plan que apruebas
Antes de escribir un solo archivo en cualquiera de los dos repositorios, te muestra el caso y la evidencia, el texto exacto de la regla que se agrega o cambia y dónde va, la revisión o el comando que se cambia, y qué casos límite cubre el arreglo y cuáles deja fuera a propósito. No se escribe nada hasta que confirmas.
Arreglado contra el archivo que falló
El arreglo se prueba en tu archivo, no en un ejemplo. Después de cambiar la regla o su revisión en el toolkit, vuelve a cargar las reglas y corre el analizador sobre el archivo que falló, una y otra vez, hasta que reporta exactamente el problema correcto en la línea correcta y nada sobre el código que es válido.
Un arreglo a un comando o a un agente se prueba, en cambio, leyendo la instrucción cambiada contra tu reporte.
Después se barre tu proyecto
Es casi seguro que el mismo patrón está en otro lado de tu proyecto. Cuando la regla ya está bien, corre esa sola regla sobre todo tu proyecto, lee cada resultado y los agrupa por patrón. Un resultado sobre código correcto quiere decir que la revisión sigue siendo demasiado amplia, y regresa a arreglar la revisión en lugar de juzgar archivo por archivo.
Recibes la lista completa: cuántos archivos, el patrón de cada grupo y una pregunta concreta por cada grupo dudoso. Ningún archivo de tu proyecto cambia antes de que lo apruebes. Luego se corrige solo lo que aprobaste, y cada archivo corregido vuelve a pasar por el analizador.
Cómo cierra
En el toolkit, una revisión cambiada recibe una prueba con el caso que falló y el caso que tiene que seguir pasando, y la prueba se corre. Un comando, agente, guía o estándar cambiado lo revisa workflow-reviewer, y a un estándar, comando o agente cambiado se le vuelve a generar su copia en español en lugar de editarla a mano. Hace un commit en el toolkit, y commits en tu proyecto agrupados por área. No se hace push de nada: publicar el cambio del toolkit te toca a ti.
Sigue por aquí
- Leer un hallazgo — de qué está hecho un hallazgo, y errores frente a advertencias.
- Escribir una regla nueva — cómo se escribe una regla cuando un caso no tiene ninguna.
- El historial de análisis — la ejecución que falló y la de después del arreglo, lado a lado.