What should happen when a repo does not run?

Most repos still fail in a strangely manual way.

You run a command.

It breaks.

Then the real work begins: reading the error, searching the README, checking `package.json`, Dockerfiles, lockfiles, CI config, and asking someone who already knows the repo what the error actually means.

That is painful for developers, but it is becoming an even bigger problem now that people are using Claude, Codex and other AI agents to understand, fix, and work inside repositories.

For example, if an agent is asked to fix a bug in an unfamiliar repo, it may need to know which setup steps matter, which command is safe to run, what dependency is missing, and what failure should block progress. If the repo cannot expose that clearly, the agent is left to guess from scattered docs, scripts, and error logs.

This is where Ota's `ota doctor` command is useful.

`ota doctor` checks a repo against its readiness contract (the `ota.yaml` file that defines what the repo needs to be considered runnable and operationally ready), then surfaces what is missing, what is blocking readiness, and what the next safe action should be.

For maintainers, that means fewer people rediscovering the same setup blocker from scratch.

For contributors, it means the repo becomes less of a guessing game.

For AI-assisted development, it gives agents a clearer operational signal before they start trying to fix things blindly.

What do you think a repo should tell you when it is not ready to run?

If you want to pressure-test this on a real repo, try Ota and share what `ota doctor` surfaces. We'd love feedback from real-world setups: https://github.com/ota-run/ota