Some backlog issues are ready to implement. Others are a title, a hunch, or a product decision that hasn't been made yet. It's easy to discover the difference only after someone has started work.
This flow reads an issue, its discussion, and the repository, then posts a readiness note. The note explains what's missing and drafts questions the author can answer before implementation begins. It leaves the issue itself unchanged.
For a conversation about an issue you're still shaping, start with GitLab's Planner agent. It can read the issue and help you work through missing details without installing a custom Flow. Use this Flow when your team wants the same review questions applied on Mention or Assign, with the result posted on the issue for its author to read.
The evaluation walkthrough shows how to improve an incomplete issue, check a ready one, and spot a misleading path or conflicting requirement. You can use the same Flow with your own code; the sample gives you familiar results to compare.
Decide where to add this check
This check is useful when your team wants to agree on what an agent needs before it starts work. An issue can sound straightforward from its title, yet leave out which code needs to change, what should stay the same, or how to test the result.
Start with an issue you expect to resolve in one merge request. The flow looks for the relevant code and points out missing acceptance criteria, constraints, or tests. If the issue still needs a product decision, it should ask the author to make that choice before anyone starts implementing it.
The note can help you see what's missing, but it won't settle product or architecture questions, plan a larger project, or handle an incident. Take those questions to the people who would normally help with them. Once an issue receives an agent-ready recommendation, review the note and hand it over through your team's usual process. This flow doesn't implement the change itself.
Understand the readiness note
The note answers five questions. Each receives a score of 0 for missing or unresolved information, 1 for useful but incomplete information, or 2 when there's enough to proceed:
- Is the expected behavior clear and testable?
- Can it locate plausible implementation entry points in the repository?
- Are constraints and out-of-scope work stated?
- Does the issue explain how to verify the result?
- Can the work fit in one merge request without an unresolved product decision?
A score from 8 to 10 can support an agent-ready recommendation, but it isn't enough by itself. The Flow also needs a confirmed code entry point, a usable way to check the result, and a task small and clear enough to implement. Otherwise, it recommends needs-spec and explains what the author can clarify or correct. Numbered criteria, bullets, and ordinary prose are all acceptable.
The note recommends a label; it doesn't apply one. You can apply agent-ready or needs-spec after reviewing it.
Before you begin
These steps follow GitLab 19.4. You'll need Duo Agent Platform enabled and AI > Flows available. GitLab's custom-flow guide explains the setup and role requirements for your offering.
To set it up, you'll need:
- A project with a codebase the flow can search.
- One intentionally vague issue and one issue that already meets your team's readiness standard.
- Maintainer or Owner access to create and enable the flow.
- A team decision about who applies the recommended label. A person can own that step until the rubric and any label automation have both been reviewed.
1. Help contributors describe the issue clearly
The sample issue template gives authors a place to describe the work and how they'll know it's done. Adapt it to your project and save it as .gitlab/issue_templates/agent_task.md on the default branch. Keep the sections that help your reviewers: context, acceptance criteria, constraints, out of scope, verification, and rollback.
The template is a starting point rather than the rubric itself. Teams can use a different issue format as long as the same information is present.
If the repository doesn't already explain its commands, owners, and change limits, adapt the relevant parts of examples/AGENTS.md into a root-level AGENTS.md. Replace every placeholder and remove sections that don't apply. The flow treats repository instructions as context to inspect, not as authority to override its safety rules.
Copy skills/issue-readiness/SKILL.md to skills/issue-readiness/SKILL.md in the target project. The flow can run without a project-level Skill, but this one gives the triage agent the issue-review method used in the examples. Automatic project Skill discovery requires Premium or Ultimate. GitLab makes project Skills available when a new Session starts, so commit the file before you begin testing.
2. Create the custom flow
Open flow.yml in the source viewer and select Copy file. In the target project:
- Go to AI > Flows and select New flow.
- Name it
Issue triage. - Describe it as a repository-aware issue readiness check.
- Set the visibility to match who should be able to reuse the flow.
- Choose Flow as the configuration type and paste the YAML.
- Create the flow and address any schema or tool warnings shown in the flow editor.
The only configured write tool is create_issue_note, which limits the flow's output to the readiness note.
3. Start with the Mention trigger
Open the Flow from Managed and select Enable. Choose your project under Project, select only Mention (mention) under Add triggers, then select Enable. That lets you choose which issue to try first and read the resulting note before running it on more of the backlog.
The metadata also supports Assign (assign). Add that trigger once the recommendations are consistent enough that assignees will understand what the flow is doing. Mention and Assign are the complete trigger set for this flow.
4. Triage an issue that needs work
Create an issue with a deliberately thin description, for example:
Title: Search is slow
The project search page takes too long. Fix it.
Mention the flow's service account:
@your-triage-service-account Check whether this issue is ready for implementation.
Read the note to see what the author still needs to explain. It should include all five rubric rows and link to the code it found. Any suggested additions to the issue should be marked as a draft for a maintainer to review. For this vague request, expect needs-spec and an unchanged issue description.
Review the suggested update as you would a draft from a teammate. Keep what's supported by the issue and repository, correct any assumptions, and make the product choices yourself. Then update the issue body.
5. Run the revised issue again
Update the issue with the decisions its author has made, then mention the service account again. The Flow reads the current issue and discussion. Earlier suggestions in a triage note aren't agreed requirements unless the author has adopted them.
Read the explanation before applying a label. Confirm that the paths exist, the verification makes sense, and the note accounts for any later comments. If the body says a zero result limit should raise an error but a comment asks for an empty list, the author needs to settle that choice first.
Apply the recommended label when you agree with the note. An agent-ready recommendation means there's enough information to start implementation; it doesn't mean the change has been implemented or its tests have passed.
Adjust the rubric for your team
You'll find the scoring and draft-writing instructions in triage_prompt inside flow.yml. Here's where to adjust them for your team:
| Team need | Where to edit |
|---|---|
| A different score threshold | Change the score ranges in triage_prompt, keeping the code, verification, and unresolved-choice checks. |
| Required design, security, or rollout fields | Add a rubric item, update the total possible score and readiness range, and adjust the included Skill to match. |
| A different issue-template shape | Change the proposed-draft instructions and adapt examples/agent-task.md. |
| More or less repository investigation | Adjust the entry-point requirement, available read tools, and conditions for stopping in triage_prompt. |
| A different label vocabulary | Change the recommendation strings in triage_prompt. |
Try a changed rubric against an issue you understand before applying it across the backlog. Compare the reasons and questions, not only the total score.
Use the note as a readiness decision
Before adding Assign, work through the evaluation cases so you know what teammates will see when assignment starts a Session automatically.
The repository search helps identify where someone might start working; it doesn't produce a complete implementation plan. If your project is a monorepo, uses generated code, or has an unusual build system, add instructions that explain how to find and test the relevant code. When the flow still can't find enough information, its needs-spec note should explain what the maintainer needs to add.
If the rubric starts producing confusing or overly broad drafts, turn off the trigger's Status toggle under AI > Triggers and review the Session and note. This prevents new runs without removing the setup; it doesn't stop an active Session. Use the specific draft to revise the prompt and rerun the case before turning the trigger back on.