What should happen when a repo does not run?

The article argues that when a repository fails to run, developers and AI agents are forced to manually reverse-engineer the codebase, relying on scattered documentation and tribal knowledge. It introduces "ota doctor," a tool that evaluates a repository against a predefined readiness contract to provide a structured diagnosis instead of a vague error. The author concludes that "good luck, read the repo" is no longer sufficient, especially for AI-assisted development.

Most repos still fail in a strangely manual way. You run a command. It breaks. Now you have to reverse-engineer the repo: That is annoying for developers, but it is a bigger problem now that AI agents are being asked to work inside unfamiliar repositories. If an AI agent is told to fix a bug, it first needs a reliable answer to some basic operational questions: In most repos, those answers are spread across docs, scripts, CI config, and tribal knowledge. That means the agent is not operating from repo truth. It is guessing. That is the problem ota doctor is meant to solve. ota doctor evaluates a repo against its readiness contract, defined in ota.yaml, and reports: So instead of “command failed, go investigate the repo,” you get a structured readiness diagnosis. For maintainers, that means fewer contributors rediscovering the same setup failures from scratch. For contributors, it means less time spent diffing docs against reality. For AI-assisted development, it gives the agent an operational signal before it starts making changes in a repo it does not yet understand. The broader question is simple: When a repo is not runnable, what should it say, and how explicitly should it say it? My view is that “good luck, read the repo” is no longer good enough. If you want to pressure-test that idea on a real codebase, try Ota and see what ota doctor surfaces: https://github.com/ota-run/ota