Azure / Azure/azure-sdk-tools

Eliminate dead-end messages — every blocker must include a next step, link, or owner

Open
#14,618 0 comments 0 reactions 0 assignees View on GitHub
AzSDK Tools Agent dev inner loop needs-triage
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
144

Description

## Problem

During the Azure Key Vault team's first SDK release, there were multiple moments where the agent told the team something was required or blocked without providing guidance on how to proceed. This forced the team to escalate through Microsoft Teams to get help — exactly the kind of friction the agent is designed to eliminate.

No agent message should leave a user stuck without a path forward.

**Source:** First-time service team feedback (Azure Key Vault)

## Proposed Solution

Enforce a "no dead ends" principle across all agent output:

**Every message that surfaces a blocker, requirement, or error must end with at least one of:**
1. A **concrete next step** — what the user should do
2. A **link** — where to go to resolve it
3. A **named owner or contact** — who can help

### Implementation approach
- Audit all agent output paths that can surface blockers or requirements
- For each path, ensure at least one of the three resolution elements is present
- Add a validation check or linting rule to catch "dead-end" messages in new code
- Consider a fallback: if no specific guidance is available, surface the Azure SDK Tools Agent support channel link

### Example — Before
> ❌ .NET package is not ready for release.

### Example — After
> ❌ .NET package `Azure.Security.KeyVault.Keys` is not ready for release.
> 👉 **Next step:** Review the blockers listed above and resolve each one.
> 💬 **Need help?** Reach out in the Azure SDK Tools Agent support channel or contact your SDK language owner.

## Acceptance Criteria

- [ ] No agent message ends with an unresolved blocker that lacks a next step, link, or named contact
- [ ] All existing blocker/requirement output paths are audited and updated
- [ ] A fallback help path (support channel link) is included when specific guidance is unavailable
- [ ] New output paths are reviewed for dead-end compliance during code review

## User Impact

Ensures service teams are never stranded during the SDK release process. Every interaction with the agent moves the user forward — even when something is blocked. This is the single most impactful UX improvement for first-time service teams, where every dead end turns into a Teams escalation.

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are named. Start by auditing the agent output paths that surface blockers, requirements, or errors, then identify how existing messages are validated. Done means all such paths provide a next step, link, or owner, with a fallback support link where specific guidance is unavailable.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.