Adapt agent verbosity and guidance for first-time service teams
- Dominant language
- C#
- Stars
- 135
- Forks
- 260
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 115
Description
## Problem
The Azure Key Vault team explicitly stated this was their first SDK release. Despite this, the agent used shorthand, assumed familiarity with SDK generation and CI pipelines, and presented checklist-style output without explaining what each item meant or what to do next.
First-time service teams need more context, not less. The current experience assumes a level of SDK process knowledge that new teams don't have.
**Source:** First-time service team feedback (Azure Key Vault)
## Proposed Solution
Add a "first-time service team" detection or explicit mode that adjusts the agent's output:
### Detection signals
- The repo/package has no prior SDK releases
- The user explicitly states it's their first release (e.g., "this is our first time releasing an SDK")
- No prior release tags exist for the package
### Behavior changes in first-time mode
1. **More explanatory language** — explain what each step means, not just what it is
2. **No shorthand or internal jargon** — spell out acronyms, avoid assumed knowledge
3. **Step-by-step framing** — present guidance as a narrative flow ("First... Then... Next...") instead of checklist-only output
4. **"What happens next" links** — at each step, link to relevant documentation or explain what the next stage of the process looks like
### Example
Instead of:
> ✅ TypeSpec compiled
> ❌ APIView approval missing
> ❌ CI failing
Provide:
> **Step 1: TypeSpec Compilation** ✅ Complete
> Your TypeSpec API definition compiled successfully. The SDK code has been generated.
>
> **Step 2: API Review** ❌ Action needed
> Before a GA release, the .NET SDK team must review your API surface to ensure it follows Azure SDK design guidelines. This protects customers from breaking changes.
> 👉 Request review at: {APIView link}
## Acceptance Criteria
- [ ] Agent detects first-time service teams via at least one signal (no prior releases, explicit user statement)
- [ ] First-time mode uses expanded explanations instead of shorthand
- [ ] Output uses step-by-step narrative framing, not checklist-only format
- [ ] Each step includes a brief explanation of *why* it matters and *what happens next*
- [ ] Mode can be explicitly toggled by the user (e.g., "explain more" or "I'm new to this")
## User Impact
Makes the Azure SDK release process accessible to service teams with zero prior experience. Reduces onboarding friction, eliminates the need for human hand-holding through the first release, and sets teams up for self-service on subsequent releases.
Contributor guide
Research direction
No files or tests are named. Start by locating the agent entry point that produces SDK release guidance and trace how user context and release history are available; compare current checklist output with the proposed first-time-team example. Done means a selectable or detected mode explains each step, uses narrative framing, and identifies why and what happens next, with coverage for the stated signals and toggle.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, csharp
- Domain
- developer-experience, release, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100