G1en-114/rtfm-first-skill

RTFM-First

Trata el manual proporcionado por el usuario como la única fuente autorizada para esta tarea. No escribas código basándote en la memoria o en materiales de internet no verificados.

Reglas de hierro

1. Cuando exista un manual, léelo antes de escribir código; los nombres de API, parámetros, valores predeterminados, unidades y comportamientos se rigen por el manual.
2. Antes de codificar, debes cotejar la versión del manual con la versión del entorno actual (consulta "Escanear entorno y cotejar versiones") e informar al usuario de la conclusión.
3. Al citar hechos clave del manual, proporciona la fuente: .rtfm/<nombre>.txt:línea o PÁGINA n.
4. Si el manual contradice el código o el entorno, no "corrijas" el código inmediatamente para que coincida con las convenciones de internet; detente, explica la diferencia y pide al usuario que decida.
5. Si no hay manual, solicita o confirma la ruta del manual; no empieces a implementar basándote en la memoria.
6. Antes de cada "corrección", debes poder señalar qué regla del manual se está violando; si no puedes proporcionar la fuente, no está permitido cambiar.

Flujo de trabajo

1. Ubicar y extraer el manual

• Si el usuario no proporciona la ruta, busca candidatos en el proyecto (*.pdf, *.md, docs/**, especificaciones mencionadas en el README); si hay varios candidatos, enuméralos y pide al usuario que confirme.
• El script se encuentra en el directorio scripts/ donde reside este SKILL.md.
• Extrae todo de manera uniforme en el directorio .rtfm/ de la raíz del proyecto (si es un repositorio git, asegúrate de que .gitignore incluya .rtfm/):
  • PDF: ejecuta scripts/extract_manual.py <manual.pdf> .rtfm/<nombre>.txt de este skill.
  • MD/TXT: también ejecuta el mismo script, que lo copiará como texto.
• Si hay varios manuales (por ejemplo, referencia de API + especificación de protocolo + documentación del SDK), extráelos todos y crea un índice para cada uno; al citar, especifica qué manual es.
• Si el PDF es un escaneo (el texto extraído es demasiado corto), informa que se necesita OCR, no adivines el contenido.
• Si el script informa "No hay extractor de texto PDF", instala poppler-utils o pypdf según las indicaciones (si se requiere instalación a nivel de sistema, primero solicita el permiso del usuario) y vuelve a intentarlo; no omitas el PDF y escribas basándote en la memoria.
• Primero lee la portada/prefacio/historial de versiones y registra: nombre del producto, versión del manual, versión aplicable, fecha, notas de revisión.

2. Crear un índice

• Ejecuta scripts/index_manual.py .rtfm/<nombre>.txt .rtfm/index.md de este skill.
• Al buscar cualquier tema, usa primero rg -n en el índice y el texto completo; no asumas que el manual no lo trata porque "no lo recuerdas".

3. Escanear el entorno y cotejar versiones

• Recopila evidencia del entorno: archivos de manifiesto/bloqueo (package.json, pyproject.toml, Cargo.lock, go.mod, requirements*.txt, etc.), --version/-V, pkg-config --modversion, versiones en tiempo de ejecución, SDK/cadena de herramientas/identificadores de hardware.
• Busca la versión del manual en la portada, historial de versiones, pie de página, metadatos.
• Determina si hay COINCIDENCIA / COMPATIBLE / DISCREPANCIA / DESCONOCIDO según references/version-matching.md.
• Escribe la conclusión en .rtfm/version-report.md e informa al usuario.
• En caso de DISCREPANCIA o DESCONOCIDO, detente: pide al usuario que proporcione un manual de la versión coincidente, o que apruebe explícitamente continuar; si aprueba, registra el riesgo en las notas.

4. Escribir código según el manual

• Antes de trabajar en cada componente/API, lee la sección completa correspondiente; extrae las firmas clave, constantes, valores predeterminados y casos límite en .rtfm/notes.md y adjunta la fuente.
• Estructura sugerida para .rtfm/notes.md: nombre del manual y versión, conclusión del cotejo de versiones (COINCIDENCIA/COMPATIBLE/DISCREPANCIA/DESCONOCIDO), extractos por tema (cada uno con manual.txt:Línea o PÁGINA n), historial de modificaciones.
• Copia los identificadores, cadenas y números del texto original del manual para evitar errores de transcripción.
• Para puntos no cubiertos por el manual, marca TODO + fuente ("tal sección del manual no lo explica"), no los completes silenciosamente con materiales de internet; si es necesario complementar, solicita primero el consentimiento del usuario.
• Lo que dice el manual vale: incluso si difiere de las "mejores prácticas" de internet, no "corrijas" repetidamente a la versión de internet, a menos que el usuario lo solicite, o que la evidencia de compilación/prueba demuestre que la página del manual no coincide con el entorno actual.

5. Verificar y finalizar

• Al terminar, revisa cada sección contra el manual: cada API/configuración/comportamiento utilizado debe tener su fuente en las notas.
• Ejecuta la compilación/prueba; si falla, primero vuelve a la sección relevante del manual para encontrar la razón, luego revisa el entorno; está prohibido adivinar.
• Al entregar, enumera brevemente: versión del manual, versión del entorno, conclusión del cotejo, fuentes principales y cualquier desviación que requiera confirmación del usuario.

Bucle de prevención de correcciones

La razón directa de la existencia de este skill: la IA no lee el manual → "corrige" el código basándose en la memoria de internet → vuelve a equivocarse → corrige de nuevo, reescribiendo repetidamente. Se deben seguir las siguientes reglas:

• Demostrar antes de modificar: antes de cada cambio de código/configuración, señala primero "qué línea del manual viola la implementación actual" y cita la fuente; sin fuente, no está permitido cambiar.
• Un solo cambio por motivo: no mezcles "no se ve bien" y "inconsistente con el manual" en una misma modificación; el código no relacionado debe permanecer igual.
• Si el mismo fenómeno aparece después de haber sido modificado dos veces: deja de parchear, vuelve al manual y relee la sección completa relevante, cuestiona tu propia comprensión, en lugar de seguir adivinando.
• Cuando el comportamiento del manual entre en conflicto con las convenciones de internet: el manual es la referencia; no conviertas código que "funciona pero no cumple con el manual" a la versión de internet, ni viceversa.
• Ante un error, consulta primero el manual: busca en las secciones de códigos de error, restricciones, condiciones límite; si el manual no tiene una entrada correspondiente, entonces revisa la evidencia del entorno; está prohibido cambiar por intuición.
• Cada modificación debe añadir una línea al historial de modificaciones de .rtfm/notes.md: objetivo, qué se cambió, fuente de la base. Si después de dos rondas de cambios aún no es correcto, primero compara el historial para encontrar repeticiones.