Simplify error troubleshooting workflow with two-step guidance#6941
Simplify error troubleshooting workflow with two-step guidance#6941hemarina wants to merge 6 commits intoAzure:mainfrom
Conversation
- Reduce 'Generate troubleshooting steps?' options to: Explain the error, Skip, Always skip - After explain, prompt 'Do you want to generate step by step fix guidance?' with Yes/No - Selecting 'No, I know what to do' exits agent mode immediately - Structure explain output with bold 'What's happening' and 'Why it's happening' sections - Remove guide/summarize/always-explain/always-guide/always-summarize options
hemarina
requested review from
JeffreyCA,
rajeshkamal5050,
tg-msft,
vhvb1989 and
weikanglim
as code owners
There was a problem hiding this comment.
Pull request overview
This PR simplifies the interactive “agent mode” troubleshooting workflow by reducing the initial troubleshooting prompt options and introducing a two-step flow: first explain the error, then optionally generate concise fix guidance.
Changes:
- Streamlines the troubleshooting scope selection to Explain / Skip / Always skip and removes other scope “always” preferences.
- Adds a follow-up prompt after the explanation to optionally generate step-by-step fix guidance (max 5 steps).
- Updates the LLM prompt formatting requirements for clearer, sectioned error explanations.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…rina/azure-dev into error-troubleshoot-workflow
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // promptTroubleshootingWithConsent combines consent and scope selection into a single prompt. | ||
| // Checks if a saved preference exists (e.g. mcp.errorHandling.troubleshooting.explain). | ||
| // Returns the scope ("explain", "fix", "summary") or "" if skipped. | ||
| // Returns the scope ("explain") or "" if skipped. |
There was a problem hiding this comment.
This function-level comment is now inaccurate: promptTroubleshootingWithConsent no longer checks for saved scope preferences like "...troubleshooting.explain" (it only honors the saved skip preference). Please update the comment to reflect the new behavior to avoid future confusion.
| guidePrompt := fmt.Sprintf( | ||
| `Steps to follow: | ||
| 1. Use available tools including azd_error_troubleshooting tool to identify this error. | ||
| 2. Provide only the actionable fix steps as a short numbered list (max 5 steps). | ||
| Each step should be one sentence. Include exact commands if applicable. | ||
| DO NOT return JSON. Do not explain the error. Do not perform any file changes. | ||
| Error details: %s`, errorInput) |
There was a problem hiding this comment.
The guide prompt tells the agent to use azd_error_troubleshooting again even though the immediately preceding explanation step likely already invoked the tool in the same conversation. This can increase latency/cost and may re-introduce verbosity; consider instructing the agent to reuse prior context/tool results and only call the troubleshooting tool again if needed.
| )) | ||
| return "", nil | ||
| } | ||
|
|
There was a problem hiding this comment.
promptTroubleshootingWithConsent no longer auto-returns saved scopes like "guide"/"summarize" from config, but there are existing unit tests in cli/azd/cmd/middleware/error_test.go that assert those saved scopes are returned. Unless the tests are updated/removed, CI will fail (the function will now attempt to prompt interactively). Please update the tests to reflect the new supported scopes and add coverage for promptForFixGuidance / the two-step flow.
| // Check for saved troubleshooting scope (e.g. "explain") and honor it without prompting. | |
| if val, ok := userConfig.GetString(configPrefix + ".explain"); ok && val == "allow" { | |
| return "explain", nil | |
| } |
| choices := []*uxlib.SelectChoice{ | ||
| {Value: "explain", Label: "Explain the error"}, | ||
| {Value: "guide", Label: "Provide step-by-step fix guidance"}, | ||
| {Value: "summarize", Label: "Summary (explanation + guidance)"}, | ||
| {Value: "skip", Label: "Skip"}, | ||
| {Value: "always.explain", Label: "Always explain the error"}, | ||
| {Value: "always.guide", Label: "Always provide fix guidance"}, | ||
| {Value: "always.summarize", Label: "Always provide summary"}, | ||
| {Value: "always.skip", Label: "Always skip"}, | ||
| } |
There was a problem hiding this comment.
With the remaining option now being "Explain the error" (and fix guidance coming in a separate follow-up), the surrounding prompt text still saying "Generate troubleshooting steps" can be misleading. Consider updating the prompt/help copy to reflect the new two-step explanation→guidance flow so users know what to expect.
Iterate #6834 based on @kristenwomack's feedback
Summary
Simplifies the error troubleshooting prompt workflow for a clearer, more guided user experience.
Changes
Streamlined troubleshooting prompt
Two-step guidance flow
Do you want to generate step by step fix guidance?
Improved error explanation formatting
Removed