What Should Happen When a Repo Does Not Run?

Most repos still fail in a manual, fragmented way.

You run a command. It breaks. Then you have to reverse-engineer the repo:

• read the error
• search the README
• inspect package.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 becomes a larger problem when AI agents are asked to work inside unfamiliar repositories.

If an agent is told to fix a bug, it first needs reliable answers to a few 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, and what is only a warning?

In most repos, those answers are scattered across docs, scripts, CI config, and tribal knowledge. 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, this 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.

When a repo is not runnable, the useful question is not just what failed. It is what the repo should say about the failure, and how explicitly it should say it.

"Good luck, read the repo" is no longer enough.