PavedPath Code

¿Qué hace PavedPath Code?

PavedPath Code ayuda a los agentes a evitar reinventar soluciones para problemas de ingeniería de software. Busca en GitHub y en la evidencia de código abierto caminos de implementación probados, y luego adapta el patrón más fuerte a la base de código local con cambios mínimos y verificables.

Utiliza GitHub como fuente de evidencia principal, no como un volcado de enlaces. El objetivo es definir el problema de código local, encontrar caminos ya recorridos en repositorios públicos, issues, pull requests, discusiones, ejemplos, notas de lanzamiento y código fuente, evaluar la solidez de esa evidencia, y luego traducir el patrón más fuerte en una pequeña corrección local, plan de implementación o plan de verificación.

Esta es la edición enfocada en código de PavedPath. No la amplíes a la PavedPath general de propósito futuro. Es para trabajo de ingeniería de software: errores, errores en tiempo de ejecución, fallos de compilación/prueba/despliegue, problemas de dependencias, uso de frameworks o APIs, bloqueos de integración, patrones de implementación, selección de herramientas de ingeniería y adaptación de soluciones de código abierto.

Cuándo Usarlo

• Errores en tiempo de ejecución, compilación, prueba, despliegue, paquetes, SDK, API, dependencias, frameworks o integraciones.
• La implementación de una funcionalidad está bloqueada por un caso límite poco claro, un patrón de uso faltante, el comportamiento de una versión o un contrato de API incierto.
• Un problema local se asemeja a algo que los mantenedores u otros usuarios de código abierto pueden haber resuelto en issues, PRs, ejemplos, código, notas de lanzamiento o discusiones.
• El usuario pregunta si GitHub o proyectos de código abierto ya han resuelto un problema de ingeniería concreto.
• Ejemplos de implementación maduros o proyectos reutilizables reducirían la incertidumbre sobre una capacidad específica.
• La respuesta debe comparar repositorios de GitHub adecuados y explicar cómo adaptar un camino probado localmente.

No uses PavedPath Code para ediciones de copia, refactorizaciones puramente locales donde la base de código ya dicta la respuesta, decisiones de vida no relacionadas con el código, flujos de trabajo de medios propios, métodos de estudio, decisiones de compra de consumo o solicitudes que prohíban explícitamente la investigación web/GitHub. No inspecciones repositorios privados a menos que el usuario lo autorice explícitamente y defina el alcance.

Flujo de Trabajo Predeterminado

1. Enmarca primero el problema de código local. Captura el objetivo, síntoma, firma de error, ruta de reproducción, versiones, entorno, nombres de dependencias/frameworks, cambios recientes, restricciones y soluciones intentadas. Si falta un hecho descubrible, inspecciona archivos/logs locales antes de preguntar.
2. Elige el modo de evidencia. Para errores/regresiones, busca primero issues, PRs, lanzamientos y código. Para necesidades de capacidad o herramientas, busca primero candidatos de repositorio. Para la implementación de funciones, usa tanto candidatos de repositorio como evidencia de issues/PRs/código.
3. Evalúa la utilidad de los subagentes. Antes de una investigación sustancial en GitHub, decide si el trabajo condicional de subagentes mejoraría la amplitud, la calidad de la evidencia o la cobertura de revisión. Si no se usan subagentes, indica brevemente la razón al informar la ruta de búsqueda.
4. Crea búsquedas dirigidas. Prefiere el texto exacto del error, nombres de paquetes/API, números de versión, framework + síntoma, nombres de archivo, claves de configuración, fragmentos de traza de pila, nombres de comandos fallidos o capacidad + nombres de framework/entorno de ejecución/API.
5. Encuentra proyectos de GitHub adecuados cuando sea relevante. Prefiere repositorios de alto ajuste, alto número de estrellas, activos, no archivados, con licencias claras y ejemplos reales. Reduce el umbral de estrellas cuando el conjunto de alto número de estrellas es demasiado amplio o no capta el problema exacto.
6. Busca en superficies de evidencia de código abierto. Usa issues, PRs, discusiones, código, ejemplos, notas de lanzamiento y documentos oficiales del proyecto dentro de repositorios de código abierto relevantes. La búsqueda de repositorios es necesaria cuando un proyecto en sí mismo puede resolver el problema.
7. Clasifica primero por ajuste al problema, con las estrellas como señal de madurez. Un repositorio con muchas estrellas es un candidato fuerte para la inspección, pero los issues confirmados por mantenedores, los PRs fusionados, las correcciones publicadas, los ejemplos oficiales y el código de coincidencia exacta superan a los proyectos populares adyacentes. Usa research-rubric.md cuando la clasificación sea importante.
8. Lee en profundidad los proyectos y la evidencia más sólidos. Usa extraction-playbook.md para extraer los conceptos básicos del proyecto, las superficies reutilizables, la causa raíz o el patrón de implementación, las restricciones de versión, los riesgos, los límites de adaptación y los pasos de verificación.
9. Traduce al trabajo local con una adaptación mínima. Conserva el flujo de trabajo probado, la API, la forma de configuración o la arquitectura donde encaje. Adapta solo las partes requeridas por las interfaces locales del usuario, configuración, modelo de datos/auth, destino de despliegue o lenguaje/entorno de ejecución.
10. Verifica antes de reclamar éxito. Usa pruebas, compilaciones, comandos de reproducción, solicitudes reales, registros, comprobaciones de navegador o inspección manual apropiados para el problema local.
11. Si la evidencia es débil, dilo. No estires coincidencias débiles para convertirlas en una recomendación segura. Marca la recomendación como basada en primeros principios o solo local cuando la evidencia de código abierto sea insuficiente.

Guía de Subagentes / Investigación Paralela

Los subagentes son ayudas de investigación condicionales, no un requisito predeterminado. El controlador sigue siendo responsable del encuadre del problema, el control del alcance, la clasificación de la evidencia, la adaptación local y la verificación final.

Usa subagentes cuando se aplique al menos una de estas condiciones:

• El problema abarca 2 o más ecosistemas, frameworks, lenguajes, herramientas, superficies de despliegue o comunidades de GitHub independientes.
• El descubrimiento de repositorios necesita una amplia cobertura de candidatos en múltiples familias de consultas.
• La evidencia de issues, PRs, discusiones, código, lanzamientos y ejemplos se puede dividir limpiamente por proyecto, versión o superficie de búsqueda.
• Una recomendación final se beneficia de una revisión de evidencia independiente, revisión de riesgos o revisión de rechazo de candidatos.

No uses subagentes cuando se aplique alguna de estas condiciones:

• La tarea es un error estrecho con un paquete, repositorio, API o superficie de mantenedor obvios.
• El contexto del repositorio local, los registros, la configuración o los detalles de reproducción deben entenderse antes de que la investigación externa pueda definirse de manera segura.
• Los límites de velocidad de GitHub, los límites de autorización, los repositorios privados, los secretos, los datos de producción o los registros sensibles harían que la delegación sea arriesgada.
• Los subagentes duplicarían principalmente las mismas búsquedas o editarían los mismos archivos locales.

Cuando se usen subagentes, el controlador debe:

• Definir la familia de consultas de cada subagente, el alcance del repositorio, la superficie de evidencia, las restricciones, el alcance de escritura permitido y la salida esperada.
• Exigir enlaces directos, metadatos verificados, justificación de ajuste al problema, notas de riesgo y razones de rechazo explícitas.
• Mantener los subagentes en modo solo lectura a menos que una fase de implementación separada tenga un alcance de escritura permitido estrecho.
• Fusionar y deduplicar los resultados antes de clasificar; no cuentes los informes repetidos del mismo issue, PR, ruta de código o repositorio como evidencia independiente.
• Verificar directamente las afirmaciones más sólidas con gh, lecturas de código fuente, pruebas, registros, solicitudes reales o documentos oficiales antes de finalizar.

CLI de GitHub Primero

Usa la CLI de GitHub (gh) como la superficie de búsqueda e inspección predeterminada. Prefiere gh search repos, gh search issues, gh search prs, gh search code, gh repo view, gh issue view, gh pr view y gh api antes que el scraping del navegador o scripts personalizados. No agregues ni confíes en scripts de búsqueda incluidos para esta habilidad.

Usa estas plantillas de comando cortas como punto de partida, luego ajusta la consulta, el repositorio, los campos y los límites al problema local:

gh search repos "<consulta>" --archived=false --sort stars --order desc --limit 10 --json fullName,url,description,stargazersCount,forksCount,language,license,pushedAt,isArchived,openIssuesCount
gh search issues "<consulta>" --repo owner/repo --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search prs "<consulta>" --repo owner/repo --merged --sort updated --order desc --limit 10 --json title,url,state,updatedAt,commentsCount,repository,body
gh search code "<consulta>" --repo owner/repo --limit 10 --json path,url,repository,sha
gh repo view owner/repo --json nameWithOwner,url,description,stargazerCount,forkCount,licenseInfo,primaryLanguage,pushedAt,repositoryTopics,homepageUrl
gh api -X GET search/repositories -f q='<consulta> archived:false' -f sort=stars -f order=desc

Ejecuta gh auth status solo cuando un comando falle con 403, 429, un error de autorización de repositorio privado o un mensaje explícito de gh no autenticado. Si GitHub devuelve 403/429, inspecciona el contexto de límite de velocidad o autorización emitido antes de reintentar, reducir la amplitud o cambiar los endpoints. No pegues ni conserves tokens, cookies, contenidos de repositorios privados o credenciales en mensajes, archivos, registros o memoria.

Estrategia de Búsqueda

• Comienza de forma estrecha: cadena de error exacta, clase de excepción, salida de CLI, nombre de paquete + método, clave de configuración o fragmento de traza de pila.
• Agrega restricciones: versión del paquete/framework, lenguaje, plataforma, destino de despliegue, empaquetador, base de datos, proveedor de autenticación o entorno de ejecución.
• Busca superficies en este orden cuando sea relevante: issues/PRs/discusiones, correcciones fusionadas, notas de lanzamiento/changelog, ejemplos/plantillas, código fuente, luego candidatos a nivel de repositorio.
• Para bloqueadores de implementación sin un error, busca la capacidad deseada más los nombres de framework/entorno de ejecución/API.
• Para necesidades de datos de plataforma pública como tendencias, listas populares, búsqueda por tema o métricas de participación, no comiences con scraping visual del navegador. Primero busca endpoints públicos reutilizables, rastreadores de código abierto, conjuntos de datos archivados y evidencia de campo de API; luego verifica la fuente elegida con una solicitud real mínima y separa claramente los datos de listas populares anónimos de los datos de búsqueda/tema con inicio de sesión.
• Para el descubrimiento de proyectos reutilizables, busca repositorios ordenados por estrellas, luego lee en profundidad solo los candidatos que coincidan con el problema local. Registra estrellas, forks, lenguaje, licencia, actividad y contenido básico.
• Degrada las coincidencias que son antiguas, con versiones no coincidentes, archivadas, no resueltas, especulativas o basadas solo en suposiciones de usuarios.
• Usa estrellas/forks solo como contexto de madurez de apoyo y desempate entre repositorios con ajuste similar. No anulan el ajuste al problema, la evidencia confirmada por mantenedores, los PRs fusionados, las notas de lanzamiento, los ejemplos oficiales o el código reproducible.
• Para seguridad, autenticación, pagos, infraestructura u operaciones de producción, verifica los hallazgos de código abierto con los documentos o repositorios oficiales actuales cuando los hechos puedan haber cambiado.

Estándar de Evidencia

Para cada elemento de evidencia importante, identifica:

• coincidencia exacta: mismo error, comportamiento, API, versión, entorno o flujo de trabajo;
• solidez de la evidencia: confirmación del mantenedor, PR fusionado, corrección publicada, ejemplo de código reproducible, fixture de prueba o informes independientes repetidos;
• aplicabilidad: qué condiciones deben coincidir localmente para que la solución se aplique;
• valor de implementación: parche, configuración, uso de API, versión de dependencia, flujo de trabajo, prueba o patrón operativo que vale la pena adaptar;
• conceptos básicos del proyecto cuando un repositorio es candidato: nombre, URL, estrellas, forks, lenguaje, licencia, actividad, contenido básico, justificación de ajuste y costo de adaptación;
• riesgo: versión obsoleta, issue no resuelto, solución insegura, preocupación de licencia, impacto en seguridad/privacidad, desajuste de despliegue o cambio demasiado amplio.

Contrato de Salida

Cuando PavedPath Code afecte materialmente la respuesta, incluye:

• perfil del problema local: objetivo, síntoma/error, versiones/entorno y restricciones locales;
• ruta de búsqueda: consultas o métodos de descubrimiento utilizados, superficies de GitHub/código abierto buscadas y si se usaron o omitieron subagentes;
• traza de subagentes cuando se usaron subagentes: alcance de cada subagente, superficies de evidencia, hallazgos clave, candidatos rechazados, resultados de deduplicación y qué afirmaciones verificó directamente el controlador;
• candidatos a proyecto cuando un proyecto de GitHub en sí mismo es relevante: enlace al repositorio, estrellas, forks, lenguaje, licencia, actividad, contenido básico, justificación de coincidencia y cómo se puede usar localmente;
• evidencia clave: enlaces a issues, PRs, código, ejemplos, lanzamientos o repositorios, con justificación de coincidencia;
• solución recomendada: qué reutilizar directamente, qué adaptar localmente, qué evitar copiar y por qué encaja;
• opciones rechazadas o riesgosas: por qué no se aplican o necesitan precaución;
• estándar de verificación: prueba, compilación, comando de reproducción, solicitud real o verificación manual necesaria para confirmar la corrección;
• etiqueta de confianza cuando la evidencia es débil o no se encontró una solución sólida de código abierto.

Cuando las soluciones a nivel de repositorio sean relevantes, incluye una tabla compacta de proyectos. Para correcciones de issues/PRs/código puros, la tabla es opcional, pero incluye contexto del repositorio si afecta la confianza o la aplicabilidad.

No respondas solo con enlaces, estrellas o clasificaciones de popularidad. No escribas "patrón común de GitHub" sin evidencia enlazada. No permitas que los ejemplos externos anulen las restricciones locales.

Para la investigación de candidatos de sitios web, SaaS, páginas de aterrizaje, temas o plantillas de frontend, incluye tanto la URL del repositorio como la URL de vista previa/demo en vivo para cada candidato serio. Si no hay vista previa disponible o verificada, indícalo explícitamente y degrada al candidato.

Nota de Migración

github-solution-research ha sido renombrado a PavedPath Code. El comportamiento anterior se conserva; esta es una actualización de nombre y posicionamiento para la edición enfocada en código de PavedPath. Las nuevas instalaciones deben usar el nombre de habilidad pavedpath-code y el directorio activo de habilidades/instrucciones del entorno de ejecución del agente objetivo.

Límites de Seguridad

• Prefiere leer patrones y reutilizar interfaces públicas existentes en lugar de copiar código. Si la reutilización de código es necesaria, verifica la licencia y mantén visibles los riesgos de atribución/obligación.
• Evita grandes reescrituras de una solución de código abierto existente. Mantén su flujo probado intacto y realiza solo las adaptaciones locales necesarias para el problema del usuario.
• Evita grandes extractos textuales de repositorios, READMEs, issues, PRs o documentación.
• No guardes tokens de GitHub, cookies, contenidos de repositorios privados o credenciales en salidas, registros, habilidades o memoria.
• No pases tokens, cookies, contenidos de repositorios privados, registros sensibles, secretos, datos de producción o credenciales a subagentes.
• Si el acceso a la red no está disponible, indica que no se pudo realizar la investigación de código abierto y marca la recomendación como solo local.