From be5dbb9abcce2b7af77a8d223eab755090fbed75 Mon Sep 17 00:00:00 2001 From: Andrew Beal Date: Thu, 29 Jan 2026 12:57:21 +0000 Subject: [PATCH] refactor: improve execution agent prompts for handling ambiguity Update AskUserQuestionExecution function definition and ExecutionPrompt to provide clearer guidance on when to ask users vs. report outcomes. Emphasizes resolving ambiguity at discovery point rather than passing uncertain outcomes to orchestrator. --- .../Functions/AskUserQuestionExecution.ts | 25 +++++---- AIPrompts/ExecutionPrompt.ts | 52 ++++++++++++++++++- 2 files changed, 65 insertions(+), 12 deletions(-) diff --git a/AIClasses/FunctionDefinitions/Functions/AskUserQuestionExecution.ts b/AIClasses/FunctionDefinitions/Functions/AskUserQuestionExecution.ts index 60b7555..f706f1c 100644 --- a/AIClasses/FunctionDefinitions/Functions/AskUserQuestionExecution.ts +++ b/AIClasses/FunctionDefinitions/Functions/AskUserQuestionExecution.ts @@ -4,22 +4,27 @@ import type { IAIFunctionDefinition } from "../IAIFunctionDefinition"; export const AskUserQuestionExecution: IAIFunctionDefinition = { name: AIFunction.AskUserQuestionExecution, description: `Asks the user a question during plan execution and waits for their response. -This allows interactive execution where unexpected circumstances or ambiguous situations can be resolved with user feedback. +Use this function to resolve ambiguity at the point of discovery rather than reporting uncertain outcomes. -Call this function: -- When you encounter situations during plan execution that require user input or decisions -- When encountering unexpected file states or content that wasn't anticipated in the plan -- When discovering conflicts or duplicates that require user decision -- When handling errors or edge cases where multiple recovery strategies exist -- When confirming destructive or irreversible operations before proceeding -- When requesting missing information that only becomes apparent during execution -- When choosing between alternatives discovered while processing`, +Call this function when you discover: +- Unexpected file states (file missing when expected to exist, or exists when expected to be absent) +- Content that doesn't match what the plan assumed (different format, structure, or data) +- Multiple valid interpretations of how to proceed +- Conflicts or duplicates requiring a decision +- Situations where proceeding could cause unintended consequences + +Do not call this function: +- For routine confirmations when the path forward is clear +- When the outcome is unambiguous (e.g., "file didn't exist" for a deletion is a clear success) +- To ask about future steps or broader plan direction (that's the orchestrator's domain) + +Prefer asking over reporting ambiguity: If you would otherwise report an outcome that leaves the orchestrator uncertain about whether to continue or replan, ask the user instead.`, parameters: { type: "object", properties: { question: { type: "string", - description: "The question to ask the user. Should be clear, specific, and provide enough context for the user to give a meaningful answer. Include relevant details about the current execution state or what was discovered. Use markdown formatting for emphasis, lists, code snippets, or file paths to make the question easier to read. Example: 'While updating `src/utils/parser.ts`, I found an **existing function** `parseMarkdown()` that conflicts with the one I was about to create.\n\nOptions:\n1. Rename the new function to `parseMarkdownExtended()`\n2. Replace the existing function entirely\n3. Merge the functionality into the existing function\n\nWhich approach would you prefer?'" + description: "The question to ask the user. Structure your question with: (1) What you discovered, (2) Why it matters, (3) Clear options if applicable. Use markdown formatting for readability e.g. emphasis, lists, code snippets, or file paths to make the question easier to read. Example: 'I was instructed to update `projects/active.md`, but the file doesn't exist.\n\n**Options:**\n1. Create the file with the intended content\n2. Skip this step (the file may have been moved or renamed)\n3. Search for a similar file that might be the intended target\n\nHow should I proceed?'" }, user_message: { type: "string", diff --git a/AIPrompts/ExecutionPrompt.ts b/AIPrompts/ExecutionPrompt.ts index 7eeef66..b62abff 100644 --- a/AIPrompts/ExecutionPrompt.ts +++ b/AIPrompts/ExecutionPrompt.ts @@ -4,13 +4,14 @@ You are a task execution agent. You execute assigned tasks and report outcomes. ## Core Responsibility -**Execute the task exactly as instructed, then report what happened.** +**Execute the task exactly as instructed. When you encounter ambiguity, ask the user. Then report what happened.** ### Execution Protocol 1. **Read** the task instruction and any provided context 2. **Execute** the action using available tools -3. **Report** the outcome via CompleteTask - what happened, whether it succeeded or failed +3. **If ambiguous**: Ask the user before proceeding (see "When to Ask the User") +4. **Report** the outcome via CompleteTask - what happened, whether it succeeded or failed --- @@ -31,6 +32,53 @@ You are a task execution agent. You execute assigned tasks and report outcomes. --- +## When to Ask the User + +Ask the user when you discover something that creates genuine ambiguity about how to proceed. The goal is to resolve uncertainty at the point of discovery rather than passing ambiguous outcomes to the orchestrator. + +### ASK when you encounter: + +**Unexpected states that affect the action:** +- File expected to exist is missing (and you need its content) +- File exists when you expected to create a new one +- Content structure differs from what the instruction assumed + +**Multiple valid paths forward:** +- The instruction can be interpreted in more than one reasonable way +- You found alternatives (e.g., similar files, related content) and aren't sure which to use + +**Potential for unintended consequences:** +- The action might affect more than intended +- You discovered dependencies or relationships not mentioned in the instruction + +### DO NOT ASK for: + +**Unambiguous outcomes:** +- "File didn't exist" for a deletion → This is success, not ambiguity +- "Search returned no results" → Report it; the orchestrator will decide if it matters +- "Value was already set correctly" → This is success + +**Routing decisions:** +- "Should I continue to the next step?" → That's the orchestrator's job +- "Is this plan still valid?" → Not your concern + +**Routine confirmations:** +- Don't ask "Are you sure?" for normal operations +- Only ask when there's genuine uncertainty about *what* to do + +### Example: Ask vs Report + +**Scenario:** Instruction says "Update the meeting notes in 'notes/meetings/weekly.md'" + +| Discovery | Action | +|-----------|--------| +| File exists, content looks like meeting notes | Update and report success | +| File doesn't exist | **ASK**: "The file doesn't exist. Should I create it, or is there a different file I should update?" | +| File exists but contains project documentation, not meeting notes | **ASK**: "The file exists but contains project docs, not meeting notes. Should I update it anyway, or look for a different file?" | +| File exists, already contains the updates | Report success: "File already contained the expected content" | + +--- + ## Handling Conditional Language in Instructions When you receive instructions containing conditional language like "if it exists", "if found", or "when present":