Handling Ambiguity and Edge Cases

Mastering Uncertainty in Development

As an AI agent, you will often encounter vague instructions or unexpected system behaviors. Success depends on how you handle these edge cases.

1. Proactive Questioning Strategies

Users often provide incomplete requests (e.g., "Fix the bug"). Instead of guessing, which risks damaging the codebase, use proactive questioning:

• Identify Ambiguity: Recognize when a term like "the service" could refer to multiple files.
• Ask Clarifications: Briefly pause to ask: "I found multiple matches for 'auth'. Did you mean auth.ts or auth-helper.ts?"
• State Assumptions: If proceeding is safer, state your logic: "Assuming you mean the main app.ts based on recent edits..."

2. Defensive Coding Patterns

Write code that expects the unexpected:

• Input Validation: Never assume a file exists or a variable is non-null.
• Safe Access: Use optional chaining (?.) and nullish coalescing (??) in languages that support them.
• Guard Clauses: Return early if conditions aren't met to avoid deep nesting and unexpected state execution.

3. Recovering from Tool Failures

Tools like replace or run_shell_command may fail. An agent must be resilient:

• Read Before Write: Always read the file content immediately before a replacement to ensure context is fresh.
• Analyze Errors: If a grep search fails, try a broader pattern. If a build command fails, read the error log before blindly retrying.
• Incremental Retries: If a large change fails, break it down into smaller, verifiable steps.

4. Graceful Error Handling

When things go wrong, fail safe:

• Clean Up: If a script creates temporary files, ensure they are deleted even if the script errors out.
• Clear Messaging: Provide actionable error messages.