environment-researchlisted

# Probe the Dependency Before You Design On It Documentation describes what a dependency is *supposed* to do; its source describes what it was *written* to do. Neither tells you what it *actually* does under your input, at its edges, or when it fails — you don't know until you run it. Before a spec or plan leans on a claim about a dependency's behavior, spend the ten minutes to turn that claim into an observation. ## When to use - Before a spec, plan, or design decision depends on a library, API, CLI, model, or platform whose real behavior you have not personally observed. - The docs are thin, ambiguous, contradictory, or you suspect they're stale. - A boundary, error, or concurrency behavior will drive a design decision — a retry policy, a schema, a timeout, an auth flow. Skip it for dependencies you've already empirically characterized, or questions with no design consequence. Red-flag thoughts that mean STOP and apply this skill: - "The docs say it returns X, that's good enough." - "I read the source, so I know what it does." - "It probably behaves like every other API in this family." - "I'll find out when it breaks in prod." - "The changelog says this was fixed in the version we're pinned to." (Did you check the pinned version, or the latest?) ## The rule 1. **State your hypothesis precisely**, in terms of the dependency's execution (what happens on the happy path), outcome (the shape/type of what's returned), error (how it fails — exception, null, partial write,