Support repository-defined ambiguity resolution and approval workflows

Summary

Allow repositories to customize, extend, or replace the default ask_user experience with repository-defined Skills and approval protocols.

Repositories can already influence how work is performed through instructions and Skills. The same should be possible for how ambiguity is resolved, approvals are obtained, and human-AI decisions are made.

Background

I have been using a custom ambiguity-resolution protocol since before ask_user existed.

Over time that protocol evolved into a repository Skill called
gated-alignment. It has served as the primary human-in-the-loop workflow
for AI-assisted changes and has required very little evolution over time.

The protocol was designed around a simple observation: ambiguity resolution
is not just about collecting an answer from the operator. It is an
opportunity for the AI and the human to develop a shared understanding of
the problem before deciding how to proceed.

When ambiguity is encountered, the Skill requires the model to present:

• multiple viable options
• rationale for each option
• trade-offs
• expected impacts
• a recommendation

This gives the operator a much better understanding of what is actually
being decided and what alternatives exist.

More importantly, it also improves the quality of the model's reasoning.
To present meaningful options, trade-offs, impacts, and recommendations,
the model must explore the solution space and develop a broader
understanding of the problem before asking for a decision.

In practice, some of the most valuable discoveries emerge during that
exploration process. Risks, assumptions, design alternatives, maintenance
concerns, and implementation constraints frequently surface before any
decision is made. Many of those insights would likely remain undiscovered
in a simple task-focused execution flow.

Because this protocol already exists and depends on these behaviors, the
Skill explicitly instructs Copilot not to use ask_user as the decision
gate itself.

The issue is therefore not that ask_user exists. The issue is that
repositories currently have no way to declare that they already have a
governance protocol for ambiguity resolution and approval workflows, or to
allow that protocol to drive the interaction experience.

Problem

Today, ambiguity resolution is effectively controlled by a generic platform workflow.

This works well for simple confirmations, but becomes limiting when repositories define their own governance protocols for:

• ambiguity resolution
• architectural decisions
• human-in-the-loop approvals
• edit authorization
• change review workflows

Repository-defined protocols can conflict with the built-in ask_user experience, especially when decisions require specific sequencing, rationale, or approval semantics.

Examples of issues include:

• Multiple unresolved approval requests being queued simultaneously.
• Generic approval prompts replacing repository-defined decision workflows.
• Loss of protocol-specific requirements such as "one active decision at a time".
• Inability to distinguish decision approval from edit authorization.
• Repository Skills having no control over how approval UX is presented.

Proposal

1. Allow repositories to disable automatic ask_user

Provide a repository-level option to manage ambiguity resolution through repository-defined Skills and instructions.

2. Allow Skills to register as ambiguity resolvers

A repository should be able to designate one or more Skills that handle ambiguity resolution and approval workflows.

When ambiguity is detected, Copilot should invoke the configured resolver instead of falling back to the generic experience.

3. Make ask_user skill-aware

Allow Skills to define interaction requirements such as:

• single active decision gate
• chat-first interaction
• option-based decisions (A/B/C/D)
• multi-stage approvals
• explicit edit-plan approval
• decision documentation requirements

The platform should preserve these requirements rather than reducing them to a generic confirmation prompt.

4. Allow custom approval UX

Skills should be able to influence how decisions are presented and resolved.

The default ask_user experience should remain available, but repositories should not be limited to it.

5. Separate decision state from execution state

Decision workflows and queued edit operations should be managed independently.

Resolving ambiguity should not require discarding pending edits, and pending edits should not create ambiguity about which decision is being approved.

These workflows are increasingly repository-specific. The platform should allow repositories to define their own ambiguity-resolution and approval contracts instead of forcing all workflows through a generic interaction model.

Example: Repository-defined ambiguity resolver

The repository below defines a custom ambiguity-resolution Skill.

---
name: gated-alignment
description: "Conduct gated alignment one decision at a time: present viable options, trade-offs and recommendations, resolve human decisions, and obtain separate edit-plan approval. Use when: invoked by repository ambiguity instructions or explicitly requested."
argument-hint: "Describe the ambiguity or decision that needs resolution"
---

# Gated Alignment Skill

Structured protocol for resolving one ambiguity at a time with the human
operator before continuing work.

## Applicability

Follow the repository's
[ambiguity instructions](../../instructions/.ambiguity.instructions.md)
for invocation policy. This skill defines the alignment protocol, not an
independent set of applicability rules.

## Chat-First Interaction

Present the complete gate in the chat: context, question, lettered options,
trade-offs and recommendation. The operator can reply directly in chat with
an option letter, an adjustment, a question or other free text. Do not require
a form submission or special response syntax.

Do not use `ask_user`, `vscode_askQuestions` or another picker/form as the gate
itself or as the required response channel. An optional `ask_user` control may
offer only the already-explained A/B/C/D choices as a selection convenience;
the complete gate must still be visible in chat. Do not put adjustment or
question collection in that control, or make it a prerequisite for continuing
the conversation. Declining, dismissing or not using it is not acceptance.

Handle adjustments, follow-up questions and edit-plan discussion through
typed chat replies.

## Protocol

### Step 1 — Frame the Decision Gate

Present exactly one decision at a time using this structure:

Decision gate: <short decision title>
Question: ❓ <single concrete question>

Option A — <label>

- Why: <why this option is relevant now>
- ✅ Pro: <at least one>
- ⚠️ Con: <at least one>
- 📈 Impact: <speed / risk / maintenance effect>

Option B — <label>

- Why: ...
- ✅ Pro: ...
- ⚠️ Con: ...
- 📈 Impact: ...

(Optional Option C / D — same structure)

⭐ Recommendation: <option + one sentence justification>
Default if no response yet: <option or "none — explicit choice required">
Reply in chat with A/B/C/D, an adjustment, or a question.

### Step 2 — Wait for Resolution

Do not continue implementation or document finalization until the gate is
resolved.

### Step 3 — Handle Response

Follow the repository's
[Read-Only and Edit Authorization policy](../../instructions/.authorization.instructions.md).
Gate acceptance resolves a decision; edit-plan approval is handled in Step 4.

| User response                         | Agent action                                     |
| ------------------------------------- | ------------------------------------------------ |
| Option letter (e.g. `A`)              | Record decision, close gate, continue to Step 4. |
| `accept: <option>`                    | Record decision, close gate, continue to Step 4. |
| Adjustment, with or without `other:`  | Refine options, re-present the same gate.        |
| Question, with or without `question:` | Answer in chat, then re-present the gate.        |
| Free-text with clear acceptance       | Record acceptance of the matching option.        |
| Unclear or noncommittal reply         | Clarify in chat; keep the same gate open.        |

Accept letters case-insensitively. A proposed adjustment is not acceptance of
an existing option; confirm the revised choice before closing the gate.
Silence or a displayed default does not resolve a pending gate.

### Step 4 — Summarize Decisions and Obtain Edit-Plan Approval

If multiple ambiguities exist, resolve them one gate at a time. After all
relevant gates are resolved:

1. Summarize accepted decisions in a compact checklist.
2. If file changes are proposed, present an edit plan identifying the files,
   intended changes, scope boundaries, and verification steps.
3. Invite the operator to comment on the plan or approve it for editing. Revise
   the plan in response to feedback and resolve any new material ambiguity.
4. Wait for explicit approval of the edit plan before editing. Acceptance of
   earlier gates is not edit-plan approval. Implement only the approved scope;
   obtain approval before expanding it.

If no file changes are proposed, state that no edits are needed and conclude
with the decision summary.

## Rules

1. Ask exactly one decision question at a time.
2. Provide 2–4 mutually exclusive options, labeled `A | B | C | D`.
3. Each option must include rationale, at least one pro, at least one con,
   and delivery impact.
4. Include one explicit recommendation grounded in repository context,
   existing code, instruction files, and available artifacts.
5. State the default action (or "none — explicit choice required") for
   low-risk cases.
6. Prioritize readability: clear headings, short bullets, visual separation.
7. Keep the complete gate in chat and accept typed replies. Forms/pickers must
   not replace the gate; optional `ask_user` use is limited to selection of
   already-explained options as described above.

This workflow depends on protocol guarantees that the current generic ask_user experience cannot express, including:

• single active decision gate
• chat-first interaction
• separation of decision approval and edit authorization
• prohibition of parallel unresolved ambiguities
• structured multi-stage approval flows

The proposal would allow Skills such as this to define and drive the ambiguity-resolution experience instead of being forced into a generic approval workflow.

Such workflows are difficult to implement reliably when the platform can independently inject generic approval prompts and queue multiple unresolved requests.

Expected outcome

Repositories should be able to define not only how AI performs work, but also how AI and humans make decisions together.

Instructions and Skills already allow repositories to govern execution. This proposal extends the same principle to ambiguity resolution, approvals, and human-in-the-loop decision making.

This would enable repository-governed ambiguity resolution, approval workflows, and human-in-the-loop controls while preserving the default experience for repositories that do not require additional governance.