Dependency Diligence

A dependency is a capability bought with a permanent liability: its bugs become your bugs, its release cadence becomes your upgrade treadmill, its transitive tree becomes your supply chain, and its API shape leaks into your design. Agents (and people) reach for a library reflexively — the evaluation discipline is what stands between "there's a package for that" and a dependency tree nobody chose on purpose.

The evaluation has a strict order, because the cheapest checks are the most decisive: constraints first, cost-per-capability second, health third. Most candidates die on the first two, before a single benchmark or changelog is read.

Three steps, and the order is the point

In full in references/the-three-steps.md.

1. The principled-constraint test. Check the project's architectural invariants first: one violated constraint rules out a whole family at once, which is far cheaper than comparing three libraries and then discovering none of them can be used.
2. Capability per cost. Weigh what it does against everything it costs — transitive tree, build time, upgrade cadence, the API surface it puts in front of your callers. A dependency that saves fifty lines and adds forty packages has not saved anything.
3. Health and fit. scripts/dep_health.py fetches the evidence — release cadence, maintainer count, open-issue shape, license. It fetches; it does not decide.

The four verdicts

Every evaluation ends in exactly one, and all four get recorded: