Hogar

Skill

Productividad y flujo de trabajo

read-the-damn-docs

BuilderIO/skills

Obliga a realizar búsquedas en Internet y a leer la documentación oficial antes de implementar, integrar o depurar API, bibliotecas y servicios de terceros, con el fin de garantizar la precisión y evitar las conjeturas.

...Expandir todo

Tiempo actualizado 6 de septiembre de 2026

# documentation # debugging # web search # api reference # best practices # third party apis

Lee los malditos documentos

No intentes adivinar dónde pueden responder a tu pregunta los documentos oficiales. Lo más habitual y acertado es buscar en Internet la documentación oficial actual, abrir las páginas pertinentes y leerlas antes de programar. En lo que respecta a las API, las versiones, el comportamiento de los proveedores, la configuración, los límites, los ganchos del ciclo de vida o los flujos sensibles en materia de seguridad, basa la respuesta en lo que realmente dice la documentación.

Motivos para dar prioridad a la documentación

Lee la documentación antes de continuar si se da alguna de estas situaciones:

El usuario pregunta por «lo último», «actual», «oficial», «compatible», «mejores prácticas», «recomendado», «hoy», «ahora» o «búscalo».
La documentación necesaria no se encuentra todavía en el repositorio ni ha sido facilitada por el usuario. Busca en la web la documentación oficial en lugar de confiar en que la memoria del modelo esté actualizada.
La tarea añade, actualiza, configura o importa un paquete, un SDK, un marco de trabajo, un complemento, una CLI, un modelo, un recurso en la nube o una integración con un proveedor.
La API evoluciona rápidamente o es sensible a las versiones: SDK de IA, API de OpenAI/Anthropic/Google, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub, Slack, Notion, API de navegadores, plataformas de despliegue, bibliotecas de autenticación y similares.
La implementación depende de la autenticación, los ámbitos de OAuth, los permisos, los secretos, los webhooks, la facturación, los pagos, la información de identificación personal (PII), el cifrado, la retención de datos, las migraciones, los reintentos, los límites de frecuencia, las cuotas, el almacenamiento en caché, los despliegues o el cumplimiento normativo.
Un error puede hacer referencia a elementos obsoletos, opciones desconocidas, exportaciones que faltan, una configuración no válida, campos no compatibles, valores predeterminados modificados o una discrepancia de versiones.
Un repositorio cuenta con documentación local, ADR, esquemas generados, especificaciones OpenAPI, registros de rutas/acciones, documentación del sistema de diseño o archivos README a nivel de paquete que podrían definir el contrato.
Revocar esta elección resulta costoso: formatos de comunicación públicos, esquema de la base de datos, estrategia de migración, identificadores persistentes, nombres de eventos, comportamiento visible para el cliente o contratos de automatización externos.
Te sorprendes a ti mismo a punto de escribir «normalmente», «probablemente», «creo», «de memoria» o código copiado de la memoria del modelo para una API externa.

¿Qué se considera documentación?

Utiliza la fuente más fidedigna disponible:

documentación del repositorio local, especificaciones, ADR, esquemas, tipos generados, archivos README de los paquetes y pruebas de comportamiento específicas del proyecto.
Documentación oficial del producto, referencias de API, guías de migración, registros de cambios, notas de lanzamiento y código fuente/tipos del SDK para el comportamiento de terceros. Búscalos mediante una búsqueda en la web cuando no tengas ya la URL exacta.
Metadatos del registro de paquetes para las versiones. Antes de añadir una dependencia, ejecuta npm view version, pnpm view versiono su equivalente en el ecosistema y, a continuación, lee la documentación de esa versión principal.
Código fuente o definiciones de tipos cuando la documentación oficial esté incompleta. Trátalo como evidencia, no como una leyenda.

Evita Stack Overflow, entradas de blog antiguas, fragmentos de código aleatorios y la memoria como fuente principal cuando existan documentos oficiales. Utiliza fuentes de la comunidad solo para depurar síntomas una vez que se conozca el contrato oficial.

Flujo de trabajo requerido

Identifica la superficie exacta: nombre del paquete, versión instalada, versión de destino, punto final del proveedor, comando de la CLI, archivo de configuración, asistente local, esquema o funcionalidad del producto.
Busca en la web la documentación oficial actual, a menos que los documentos relevantes ya estén disponibles localmente o el usuario haya facilitado una URL. Utiliza búsquedas específicas como official docs, migration guide, o API reference.
abre y lee la documentación más cercana a esa superficie. Da prioridad primero a la documentación local para el código interno y, a continuación, a la documentación oficial del desarrollador original. Para los paquetes nuevos, verifica la última versión antes de escribir importaciones, configuraciones o comandos de instalación.
Extrae los pocos datos necesarios para la tarea: nombres de opciones, importaciones, reglas del ciclo de vida, comportamiento predeterminado, cambios incompatibles, límites, permisos y ejemplos para la versión principal actual.
Implementa o responde utilizando esos datos. Si la documentación entra en conflicto con el código existente, revisa la ruta del código local y señala la discrepancia.
Verifica con la comprobación útil más sencilla: comprobación de tipos, pruebas, compilación, ejecución de prueba de la CLI, validación del esquema de la API o una reproducción local.
En la respuesta final, indica los documentos o archivos locales consultados cuando dicha evidencia afecte a la recomendación o a la implementación.

Ejemplos que deben dar lugar a documentación

«Añade Tailwind a esta aplicación». Comprueba la versión principal actual de Tailwind y su documentación de instalación en la web antes de crear archivos de configuración o dar por hecho una configuración antigua de PostCSS.
«Utiliza el SDK de IA para transmitir respuestas». Verifica la versión principal actual del SDK de IA, las importaciones, los nombres de los paquetes de los proveedores, los ayudantes de transmisión y los ejemplos de servidor/tiempo de ejecución en la documentación oficial.
«Configurar los webhooks de Stripe». Lee la documentación actual de Stripe sobre verificación de firmas, reintentos de eventos, secretos de puntos finales y análisis del cuerpo de la solicitud antes de programar.
«Soluciona este error de almacenamiento en caché de Next.js». Lee la documentación de la versión principal de Next.js instalada y del modo de enrutador antes de dar por sentada la semántica de invalidación de la caché.
«Añade migraciones de Drizzle». Lee la documentación actual del kit de Drizzle y las convenciones de migración existentes en el repositorio antes de generar archivos.
«Crear una acción de GitHub». Lee la documentación oficial sobre sintaxis y permisos de las acciones, especialmente en lo relativo a pull_request, workflow_run, OIDC, los tokens y los artefactos.
«¿Por qué falla este flujo de OAuth?». Lee la documentación del proveedor sobre ámbitos, URI de redirección, PKCE, actualización de tokens y verificación de aplicaciones antes de modificar el código.
«Utiliza el sistema de planes/comentarios/acciones de este repositorio». Lee la documentación local, los registros de rutas/acciones, los esquemas y las pruebas antes de inventar puntos finales o propiedades.
«Actualiza Vite/Nitro/React». Lee la guía de migración para conocer la versión principal de destino exacta antes de editar la configuración o las importaciones.
«¿Qué modelo deberíamos utilizar?» Lee la documentación actual sobre los modelos del proveedor, las páginas de precios y límites y los ejemplos del SDK antes de hacer recomendaciones.

Cuando basta con una lectura rápida local

No busques en Internet cada vez que haya que hacer una pequeña modificación. Una revisión de la documentación puede ser local y breve cuando la respuesta ya está en el repositorio: uso de ayudantes existentes, pruebas cercanas, interfaces tipadas, clientes generados, ADR o archivos README de los paquetes. Pero si la tarea depende de una herramienta externa, un paquete, un proveedor o el comportamiento actual del producto, la búsqueda en la web suele ser el primer paso adecuado. Para cuestiones triviales de sintaxis del lenguaje, correcciones de errores tipográficos, formato o código autónomo sin contrato externo, procede con normalidad.

Si la documentación no está disponible

Si el acceso a la red, la autenticación o la falta de archivos locales impiden leer la documentación, indícalo claramente antes de basarte en la memoria. Reduce la incertidumbre, examina el código fuente o los tipos si están disponibles, y evita presentar el resultado como si fuera una información actualizada y confirmada.

Ver en GitHub

---
name: read-the-damn-docs
description: Forces web searches and reading of official docs before implementing, integrating, or debugging third-party APIs, libraries, and services to ensure accuracy and avoid guesswork.
---

# Read The Damn Docs

Do not guess where authoritative docs can answer the question. The most common
right move is to web-search for the current official docs, open the relevant
pages, and read them before coding. For APIs, versions, provider behavior,
config, limits, lifecycle hooks, or security-sensitive flows, ground the answer
in what the docs actually say.

## Docs-First Triggers

Read docs before proceeding when any of these are true:

- The user asks for "latest", "current", "official", "supported", "best
  practice", "recommended", "today", "now", or "look it up".
- The needed docs are not already in the repo or supplied by the user. Search
  the web for the official docs rather than hoping model memory is current.
- The task adds, upgrades, configures, or imports a package, SDK, framework,
  plugin, CLI, model, cloud resource, or provider integration.
- The API is fast-moving or version-sensitive: AI SDKs, OpenAI/Anthropic/Google
  APIs, Next.js, React, Tailwind, Vite, Nitro, Drizzle, Prisma, Stripe, GitHub,
  Slack, Notion, browser APIs, deployment platforms, auth libraries, and similar.
- The implementation depends on auth, OAuth scopes, permissions, secrets,
  webhooks, billing, payments, PII, encryption, data retention, migrations,
  retries, rate limits, quotas, caching, deploys, or compliance.
- An error mentions deprecation, unknown options, missing exports, invalid
  config, unsupported fields, changed defaults, or version mismatch.
- A repo has local docs, ADRs, generated schemas, OpenAPI specs, route/action
  registries, design-system docs, or package-level READMEs that could define the
  contract.
- The choice is expensive to reverse: public wire formats, database schema,
  migration strategy, persistent IDs, event names, customer-visible behavior, or
  external automation contracts.
- You catch yourself about to write "usually", "probably", "I think", "from
  memory", or code copied from model memory for an external API.

## What Counts As Docs

Use the most authoritative source available:

- Local repo docs, specs, ADRs, schemas, generated types, package READMEs, and
  tests for project-specific behavior.
- Official product docs, API references, migration guides, changelogs, release
  notes, and SDK source/types for third-party behavior. Find these with web
  search when you do not already have the exact URL.
- Package registry metadata for versions. Before adding a dependency, run
  `npm view <pkg> version`, `pnpm view <pkg> version`, or the ecosystem
  equivalent, then read the docs for that major version.
- Source code or type definitions when official docs are incomplete. Treat this
  as evidence, not folklore.

Avoid Stack Overflow, old blog posts, random snippets, and memory as the primary
source when official docs exist. Use community sources only to debug symptoms
after the authoritative contract is known.

## Required Workflow

1. Identify the exact surface: package name, installed version, target version,
   provider endpoint, CLI command, config file, local helper, schema, or product
   feature.
2. Search the web for the current official docs unless the relevant docs are
   already local or the user supplied a URL. Use targeted searches such as
   `<product> <feature> official docs`, `<package> migration guide`, or
   `<provider> API reference`.
3. Open and read the docs closest to that surface. Prefer local docs first for
   internal code, then official upstream docs. For new packages, verify the
   latest version before writing imports, config, or install commands.
4. Extract the few facts needed for the task: option names, imports, lifecycle
   rules, default behavior, breaking changes, limits, permissions, and examples
   for the current major version.
5. Implement or answer using those facts. If the docs conflict with existing
   code, inspect the local code path and call out the discrepancy.
6. Verify with the smallest useful check: typecheck, tests, build, CLI dry run,
   API schema validation, or a local reproduction.
7. In the final answer, name the docs or local files consulted when that
   evidence affects the recommendation or implementation.

## Examples That Must Trigger Docs

- "Add Tailwind to this app." Check the current Tailwind major and its install
  docs from the web before creating config files or assuming old PostCSS setup.
- "Use the AI SDK to stream responses." Verify the current AI SDK major,
  imports, provider package names, streaming helpers, and server/runtime
  examples from official docs.
- "Wire up Stripe webhooks." Read Stripe's current signature verification,
  event retry, endpoint secret, and framework body-parsing docs before coding.
- "Fix this Next.js caching bug." Read the docs for the installed Next.js major
  and router mode before assuming cache invalidation semantics.
- "Add Drizzle migrations." Read the current Drizzle kit docs and existing repo
  migration conventions before generating files.
- "Create a GitHub Action." Read official Actions syntax and permissions docs,
  especially for `pull_request`, `workflow_run`, OIDC, tokens, and artifacts.
- "Why does this OAuth flow fail?" Read the provider's scopes, redirect URI,
  PKCE, token refresh, and app verification docs before changing code.
- "Use this repo's plan/comment/action system." Read local docs, route/action
  registries, schemas, and tests before inventing endpoints or props.
- "Upgrade Vite/Nitro/React." Read the migration guide for the exact target
  major before editing config or imports.
- "What model should we use?" Read current provider model docs, pricing/limits
  pages, and SDK examples before recommending.

## When A Quick Local Read Is Enough

Do not browse the web for every tiny edit. A docs pass can be local and brief
when the answer is already in the repo: existing helper usage, nearby tests,
typed interfaces, generated clients, ADRs, or package READMEs. But if the task
depends on an external tool, package, provider, or current product behavior, web
search is usually the right first step. For trivial language syntax, typo fixes,
formatting, or self-contained code with no external contract, proceed normally.

## If Docs Are Unavailable

If network access, auth, or missing local files prevents reading the docs, say
that plainly before relying on memory. Narrow the uncertainty, inspect source or
types if available, and avoid presenting the result as confirmed-current.