Most repos still fail in a strangely manual way.
You run a command.
It breaks.
Now you have to reverse-engineer the repo:
- read the error
- search the README
- inspectpackage.json, Docker files, and lockfiles
- compare local state with CI
- ask someone who already knows
- try a few fixes and hope one is the real one
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:
- What does this repo require to run?
- Which workflow is the intended front door?
- Which missing dependency is actually blocking readiness?
- Which commands are safe to run?
- What should stop progress vs what is only a warning?
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:
- whether the repo is ready
- what is missing
- what is blocking readiness
- what is only degraded or advisory
- the next safe action to take
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
