How to Write Agent-Ready Engineering Issues

An agent-ready issue states the observable problem, reproduction, desired result, constraints, validation commands, and non-goals in language a reviewer can later use to judge the diff.

This guide focuses on the engineering decision behind agent ready issue template: what to standardize, what to constrain, and what evidence a reviewer should expect before accepting the result.

The core decision

Lead with behavior rather than an implementation guess. Include the exact error or user-visible outcome, the relevant repository area, and a minimal reproduction. Name compatibility, performance, security, and API constraints that must survive.

A workflow that holds up in review

End with a checklist the agent can execute and the reviewer can repeat. Link to current examples inside the repository, not stale external snippets. If discovery is still required, label the first task as investigation and request a plan or failing test.

The failure mode to design around

A ticket full of historical discussion can obscure the final decision. Summarize the current contract at the top and keep background below it. Remove contradictory acceptance criteria before dispatch.

Implementation checklist

Describe current and desired behavior.
Provide a deterministic reproduction.
List constraints and non-goals.
Name exact validation commands.

Turn the checklist into operating controls

Describe current and desired behavior: name the owner, the evidence that proves it happened, and the condition that should stop the run.
Provide a deterministic reproduction: name the owner, the evidence that proves it happened, and the condition that should stop the run.
List constraints and non-goals: name the owner, the evidence that proves it happened, and the condition that should stop the run.
Name exact validation commands: name the owner, the evidence that proves it happened, and the condition that should stop the run.

The list becomes useful when every item produces visible evidence. Store that evidence with the task or pull request rather than in a private chat. A future reviewer should be able to tell which repository revision was used, which permission profile applied, what stopped or failed, and who accepted the remaining risk. For agent ready issue template, a short, complete record is more valuable than a long narrative that cannot be reproduced.

Move from one run to a repeatable practice

Pilot the workflow with engineers who will both dispatch and review tasks. Watch where they add missing context, where the agent asks for clarification, and where reviewers cannot reconstruct the intent. Turn repeated explanations into repository guidance or issue templates, but keep product decisions in the task itself. Review queue time as carefully as execution time. The workflow is healthy only when completed artifacts are reviewed promptly and rejected work improves the next task packet.

Before expanding the workflow, ask three review questions:

What evidence shows that describe current and desired behavior was satisfied, and would that evidence survive a rerun from the recorded commit?
What evidence shows that provide a deterministic reproduction was satisfied, and would that evidence survive a rerun from the recorded commit?
What evidence shows that list constraints and non-goals was satisfied, and would that evidence survive a rerun from the recorded commit?

Write the answers in the same place as the code review. That creates a compact decision record and lets the team compare later runs without relying on memory.

A practical acceptance test

Run the workflow from a clean checkout at a recorded commit. Give the agent only the documented task packet and the intended permission profile. Then ask a reviewer who did not launch the run to reproduce the important checks, explain the changed behavior, and identify the rollback path. The task passes only when the artifact, evidence, and repository state agree. Keep the failed examples as regression cases; they are more useful than a polished demo because they reveal where instructions, environment, permissions, or tests need improvement.

Primary references

Vendor features, limits, preview labels, and pricing can change. Recheck the linked first-party documentation for the current state before making a purchase or rollout decision.