Improve on triage agent prompt

[PeyGis]

User description

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.

Added docs pages

Please also include the path for the added docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

Updated docs pages

Please also include the path for the updated docs

• Quickstart (/)
• Blueprint (/platform-overview/port-components/blueprint)
• ...

---

PR Type

Enhancement, Documentation

---

Description

• Restructured AI triage agent prompt for clarity and specificity

• Added explicit guidance on handling missing information with placeholders

• Improved formatting with better section organization and examples

• Enhanced instructions to prevent AI from inventing content

---

Diagram Walkthrough

flowchart LR
  A["Original Prompt"] -- "Restructure steps" --> B["Enhanced Prompt"]
  B -- "Add placeholder examples" --> C["Better Missing Data Handling"]
  C -- "Improve formatting" --> D["Clearer Agent Instructions"]

Loading

File Walkthrough

Relevant files

Documentation

triage-tickets-to-coding-agents.md Restructure and clarify AI triage agent prompt instructions docs/guides/all/triage-tickets-to-coding-agents.md Reorganized the "Gather Context" step with improved formatting and backtick-wrapped tool names Enhanced "Evaluate Description" step with bullet points and explicit guidance on template handling Expanded "Identify Gaps" section with concrete placeholder examples using warning emoji Added explicit instruction to prevent AI from inventing content when data is unavailable Improved overall readability with better markdown formatting and structured examples +1/-1

---

[qodo-merge-pro]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No runtime logs: The added changes modify prompt text in documentation without adding or removing any runtime code or logging, so audit trail compliance cannot be assessed from this diff alone. Referred Code "properties": { "description": "An agent that evaluate whether a ticket has sufficient context and well-defined requirements for successful execution by a coding agent", "status": "active", "prompt": "Your task is to evaluate and improve Jira tickets before coding agent execution.\n\n### Steps\n1. **Gather Context:**\n If the ticket is linked to other entities (e.g. service, repo, or project), retrieve them using available tools (`get_entities_by_identifiers`, `list_blueprints`, etc.) and extract relevant details such as README, owners, dependencies, configurations, or architecture notes. Use these to enrich the ticket context.\n\n2. **Evaluate Description:**\n Compare the ticket’s description with the project’s success criteria or an embedded PRD/template.\n\n * If a template exists, treat it as canonical — fill in each section using verified data from the ticket or related entities.\n * If a section lacks enough data, **do not invent content**. Instead, insert a clear placeholder such as:\n\n > ⚠️ Requires more information — please describe [database configuration / email service / environment setup].\n\n3. **Identify Gaps:**\n When details cannot be found in either the ticket or its linked entities, explicitly state this under the relevant section. Examples:\n\n * “⚠️ Requires more information — database schema details not found in repository or catalog.”\n * “⚠️ Requires more information — email provider (SendGrid/AWS SES) not specified.”\n\n4. **Score (0–100):** Rate the ticket’s completeness and clarity.\n5. **Assign Stage:** Use “Awaiting approval” if AI edits are proposed, “Approved” if the ticket meets success criteria already\n\n## Response Rules\n\n1. ALWAYS respond by calling the `ask_ai_to_improve_on_ticket` self-service action with:\n\n ```json\n {\n \"actionIdentifier\": \"ask_ai_to_improve_on_ticket\",\n \"properties\": {\n \"ticket\": \"<provided entity identifier>\",\n \"current_stage\": \"<determined stage>\",\n \"confidence_score\": <number 0-100>\n \"ai_suggested_description\": \"<markdown-formatted with filled template or empty if already perfect>\"\n }\n }\n ```\n\n### Rules\n* Always include `confidence_score` and `current_stage`.\n* If score < 90 → rewrite ticket with enriched context and clearly flagged missing data.\n* If score ≥ 90 → leave `ai_suggested_description` with empty string (ticket appears complete).\n* Be concise, data-grounded, and specific about what info was found vs. missing under the respective section in the template.", "execution_mode": "Automatic", "tools": [ "^(list|get|search|track|describe)_.*",
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Not applicable here: The diff only updates documentation prompt text and does not introduce executable logic where error handling could be evaluated. Referred Code "properties": { "description": "An agent that evaluate whether a ticket has sufficient context and well-defined requirements for successful execution by a coding agent", "status": "active", "prompt": "Your task is to evaluate and improve Jira tickets before coding agent execution.\n\n### Steps\n1. **Gather Context:**\n If the ticket is linked to other entities (e.g. service, repo, or project), retrieve them using available tools (`get_entities_by_identifiers`, `list_blueprints`, etc.) and extract relevant details such as README, owners, dependencies, configurations, or architecture notes. Use these to enrich the ticket context.\n\n2. **Evaluate Description:**\n Compare the ticket’s description with the project’s success criteria or an embedded PRD/template.\n\n * If a template exists, treat it as canonical — fill in each section using verified data from the ticket or related entities.\n * If a section lacks enough data, **do not invent content**. Instead, insert a clear placeholder such as:\n\n > ⚠️ Requires more information — please describe [database configuration / email service / environment setup].\n\n3. **Identify Gaps:**\n When details cannot be found in either the ticket or its linked entities, explicitly state this under the relevant section. Examples:\n\n * “⚠️ Requires more information — database schema details not found in repository or catalog.”\n * “⚠️ Requires more information — email provider (SendGrid/AWS SES) not specified.”\n\n4. **Score (0–100):** Rate the ticket’s completeness and clarity.\n5. **Assign Stage:** Use “Awaiting approval” if AI edits are proposed, “Approved” if the ticket meets success criteria already\n\n## Response Rules\n\n1. ALWAYS respond by calling the `ask_ai_to_improve_on_ticket` self-service action with:\n\n ```json\n {\n \"actionIdentifier\": \"ask_ai_to_improve_on_ticket\",\n \"properties\": {\n \"ticket\": \"<provided entity identifier>\",\n \"current_stage\": \"<determined stage>\",\n \"confidence_score\": <number 0-100>\n \"ai_suggested_description\": \"<markdown-formatted with filled template or empty if already perfect>\"\n }\n }\n ```\n\n### Rules\n* Always include `confidence_score` and `current_stage`.\n* If score < 90 → rewrite ticket with enriched context and clearly flagged missing data.\n* If score ≥ 90 → leave `ai_suggested_description` with empty string (ticket appears complete).\n* Be concise, data-grounded, and specific about what info was found vs. missing under the respective section in the template.", "execution_mode": "Automatic", "tools": [ "^(list|get|search|track|describe)_.*",
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Doc-only change: The changes adjust documentation for an AI prompt and do not show input handling or data processing code to validate against security requirements. Referred Code "properties": { "description": "An agent that evaluate whether a ticket has sufficient context and well-defined requirements for successful execution by a coding agent", "status": "active", "prompt": "Your task is to evaluate and improve Jira tickets before coding agent execution.\n\n### Steps\n1. **Gather Context:**\n If the ticket is linked to other entities (e.g. service, repo, or project), retrieve them using available tools (`get_entities_by_identifiers`, `list_blueprints`, etc.) and extract relevant details such as README, owners, dependencies, configurations, or architecture notes. Use these to enrich the ticket context.\n\n2. **Evaluate Description:**\n Compare the ticket’s description with the project’s success criteria or an embedded PRD/template.\n\n * If a template exists, treat it as canonical — fill in each section using verified data from the ticket or related entities.\n * If a section lacks enough data, **do not invent content**. Instead, insert a clear placeholder such as:\n\n > ⚠️ Requires more information — please describe [database configuration / email service / environment setup].\n\n3. **Identify Gaps:**\n When details cannot be found in either the ticket or its linked entities, explicitly state this under the relevant section. Examples:\n\n * “⚠️ Requires more information — database schema details not found in repository or catalog.”\n * “⚠️ Requires more information — email provider (SendGrid/AWS SES) not specified.”\n\n4. **Score (0–100):** Rate the ticket’s completeness and clarity.\n5. **Assign Stage:** Use “Awaiting approval” if AI edits are proposed, “Approved” if the ticket meets success criteria already\n\n## Response Rules\n\n1. ALWAYS respond by calling the `ask_ai_to_improve_on_ticket` self-service action with:\n\n ```json\n {\n \"actionIdentifier\": \"ask_ai_to_improve_on_ticket\",\n \"properties\": {\n \"ticket\": \"<provided entity identifier>\",\n \"current_stage\": \"<determined stage>\",\n \"confidence_score\": <number 0-100>\n \"ai_suggested_description\": \"<markdown-formatted with filled template or empty if already perfect>\"\n }\n }\n ```\n\n### Rules\n* Always include `confidence_score` and `current_stage`.\n* If score < 90 → rewrite ticket with enriched context and clearly flagged missing data.\n* If score ≥ 90 → leave `ai_suggested_description` with empty string (ticket appears complete).\n* Be concise, data-grounded, and specific about what info was found vs. missing under the respective section in the template.", "execution_mode": "Automatic", "tools": [ "^(list|get|search|track|describe)_.*",

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-merge-pro]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Enhancement	Clarify agent's response for low scores Clarify the instruction for scores below 90 by explicitly stating that the ai_suggested_description field should contain the rewritten ticket. docs/guides/all/triage-tickets-to-coding-agents.md [555] -* If score < 90 → rewrite ticket with enriched context and clearly flagged missing data. -* If score ≥ 90 → leave `ai_suggested_description` with empty string (ticket appears complete). +* If score < 90 → `ai_suggested_description` should contain the rewritten ticket with enriched context and clearly flagged missing data. +* If score ≥ 90 → leave `ai_suggested_description` with an empty string (ticket appears complete). [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 6 __ Why: The suggestion improves the prompt's clarity by explicitly linking the "rewrite ticket" instruction to the ai_suggested_description field, reducing ambiguity for the AI agent.	Low
	Instruct agent to avoid making assumptions Add an explicit instruction for the agent to "not make assumptions" to reinforce being data-grounded and reduce the risk of hallucination. docs/guides/all/triage-tickets-to-coding-agents.md [555] -* Be concise, data-grounded, and specific about what info was found vs. missing under the respective section in the template. +* Be concise, data-grounded, and specific about what info was found vs. missing under the respective section in the template. Do not make assumptions. [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 5 __ Why: The suggestion reinforces an existing instruction ("do not invent content") by adding "Do not make assumptions." While this improves the prompt, its impact is moderate as it's somewhat redundant.	Low
	Add a period to complete the sentence Add a period to the end of the sentence in step 5, "Assign Stage", to make it grammatically complete. docs/guides/all/triage-tickets-to-coding-agents.md [555] -5. **Assign Stage:** Use “Awaiting approval” if AI edits are proposed, “Approved” if the ticket meets success criteria already +5. **Assign Stage:** Use “Awaiting approval” if AI edits are proposed, “Approved” if the ticket meets success criteria already. [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 2 __ Why: The suggestion correctly points out a missing period, but this is a minor grammatical fix with negligible impact on the prompt's effectiveness or the AI's behavior.	Low
Organization best practice	Add showLineNumbers to code block Add showLineNumbers to the multi-line JSON code block to improve readability and copying consistency across docs. docs/guides/all/triage-tickets-to-coding-agents.md [555] -```json +```json showLineNumbers { "actionIdentifier": "ask_ai_to_improve_on_ticket", "properties": { "ticket": "<provided entity identifier>", "current_stage": "<determined stage>", "confidence_score": <number 0-100> "ai_suggested_description": "<markdown-formatted with filled template or empty if already perfect>" } } `[To ensure code accuracy, apply this suggestion manually]` <details><summary>Suggestion importance[1-10]: 6</summary> __ Why: Relevant best practice - Pattern 4 and 14: Specify language for all code fences and add showLineNumbers to multi-line code blocks. </details></details></td><td align=center>Low </td></tr> <tr><td align="center" colspan="2"> - [ ] More <!-- /improve --more_suggestions=true --> </td><td></td></tr></tbody></table>

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2975.d2ngvl90zqbob8.amplifyapp.com