Why IssueReady exists: the issue-to-agent handoff gap

[whyiug]

IssueReady did not originate from one upstream feature request. It responds to a recurring handoff problem visible across platform guidance, research, and independent maintainer workflows.

The recurring signal

GitHub recommends giving coding agents a clear problem, complete acceptance criteria, relevant file guidance, and a bounded task. Its WRAP guidance similarly treats effective issues and atomic tasks as prerequisites for working through an existing backlog.

The paper What Makes a GitHub Issue Ready for Copilot? turns that intuition into 32 detailed criteria and reports associations between merge outcomes and issues that are well scoped, provide implementation guidance, and point to relevant artifacts. That is useful evidence, but an association or model score is not an authorization decision.

Independent projects describe the same missing front-of-funnel:

• easy-cheese #156 asks for a needs-triage → needs-info → ready-for-agent lifecycle before Agent Brief generation.
• loomux #265 proposes interrogating vague issues for constraints, non-goals, acceptance criteria, and unknowns before applying agent-ready.
• podcast_scraper #51 describes variable issue quality and a quality gate before assigning Copilot.

These projects are independent examples, not endorsements of IssueReady.

The gap IssueReady addresses

IssueReady keeps three questions separate:

1. Did evaluation complete with enough trustworthy context?
2. Is the specification ready without inventing requirements?
3. Does repository policy permit unsupervised delegation?

This prevents a permission failure or missing semantic coverage from becoming an author-blaming NEEDS_INFO, and prevents a well-written task from silently granting execution authority. The CLI is local-first and read-only; it does not edit issues or run coding agents.

Try the reviewed demos:

npx issueready demo ready
npx issueready demo needs-info

Or evaluate a public issue:

npx issueready owner/repository#123 --format markdown

If you maintain a real backlog, I would especially value examples where “ready,” “needs clarification,” and “safe to delegate” diverge. Please use public or synthetic issue content only.