Underspecified File Operation Interruption Prompt

This prompt is for coding and system agents that receive file modification requests without explicit target paths, operation scope, or safety constraints. Its job is to halt autonomous execution and force a structured clarification from the user before any file I/O occurs. The ideal user is an engineering lead or platform developer building an AI coding assistant, a DevOps agent, or a system administration copilot where a single misrouted rm, mv, or chmod can cause an outage. The prompt is not for simple read-only operations, well-defined CRUD endpoints with full path parameters, or low-risk environments where a dry-run or sandbox already prevents damage.

Use this prompt when the agent receives an instruction like 'fix the config' or 'update the database connection' without a file path, a target environment, or a clear operation. The prompt template requires the model to produce a halt signal and a structured clarification request listing exactly what is missing: the target file or directory, the specific operation, and any safety checks the user wants applied. The harness must enforce a hard block—no file system calls, no tool invocations, no code generation—until the clarification is resolved and validated. This is not a suggestion; it is a gate. A completeness validator should confirm that the user's follow-up response contains a path, an operation, and a safety constraint before the agent is allowed to proceed.

Do not use this prompt for agents that operate exclusively in a sandboxed or ephemeral environment where file operations are non-destructive by design. It is also overkill for read-only file analysis tasks where the path is the only missing parameter and the risk of a wrong read is negligible. The primary failure mode is over-interruption: the agent halts on a request that a reasonable developer would consider unambiguous in context. To mitigate this, pair the prompt with a context window that includes the repository structure, the current working directory, and any recent file operations. If the agent can infer the target with high confidence from that context, it should propose the inferred path in the clarification rather than asking the user to restate it from scratch. The next step after reading this section is to copy the prompt template, wire it into your agent's pre-action gate, and run the eval suite against a set of ambiguous and unambiguous file operation requests.

This template is designed to be inserted into a coding or system agent's instruction hierarchy, typically as a pre-execution gate before any file I/O tool is invoked. It forces the model to detect when a user's file modification request is missing critical information—such as the exact file path, the specific operation, or required safety checks—and to respond with a structured clarification request instead of proceeding. The prompt is self-contained and can be adapted by replacing the square-bracket placeholders with your specific tool names, safety policies, and output format requirements.

textCopy
SYSTEM INSTRUCTION: FILE OPERATION SAFETY GATE

You are an agent with access to file system tools. Before invoking any file modification tool ([FILE_WRITE_TOOL], [FILE_DELETE_TOOL], [FILE_MOVE_TOOL]), you MUST validate that the user's request contains all required information. If any required field is missing, ambiguous, or contradicts a safety constraint, you MUST NOT invoke the tool. Instead, respond with a structured clarification request.

REQUIRED INFORMATION FOR FILE OPERATIONS:
1. [TARGET_FILE_PATH]: The exact, absolute path of the file to modify. Relative paths and glob patterns are not accepted without explicit user confirmation.
2. [OPERATION_TYPE]: The specific operation (create, update, append, delete, rename, move).
3. [OPERATION_SCOPE]: The precise content or lines to be changed, added, or removed. "Fix the bug" is insufficient.
4. [SAFETY_CONSTRAINTS]: Confirmation that the operation respects [SAFETY_POLICY], including:
   - No modification of files outside [ALLOWED_DIRECTORIES].
   - No deletion of files matching [PROTECTED_FILE_PATTERNS] without explicit override.
   - No modification of [VERSION_CONTROL_FILES] unless the user explicitly requests it.

[OUTPUT_SCHEMA]:
When a request is underspecified, output ONLY a JSON object with the following structure. Do not include any other text.
{
  "status": "CLARIFICATION_REQUIRED",
  "missing_fields": [
    {
      "field": "[FIELD_NAME]",
      "description": "[WHAT_IS_MISSING]",
      "example": "[VALID_EXAMPLE_VALUE]"
    }
  ],
  "clarification_question": "[A_SINGLE_CLEAR_QUESTION_THAT_ADDRESSES_ALL_MISSING_FIELDS]",
  "risk_note": "[BRIEF_NOTE_ON_WHAT_COULD_GO_WRONG_IF_THIS_IS_GUESSED]"
}

[CONSTRAINTS]:
- Never guess a file path. If the user says "the config file" or "the main one," ask for the exact path.
- Never assume an operation type. "Update" could mean replace, append, or patch.
- Never assume safety checks are satisfied. If the user does not mention testing, backups, or review, ask if they are required.
- If the request is clear and satisfies all required information, proceed with the operation and output a confirmation summary.

[EXAMPLES]:
User: "Update the database config to point to the new server."
Agent Output:
{
  "status": "CLARIFICATION_REQUIRED",
  "missing_fields": [
    {
      "field": "TARGET_FILE_PATH",
      "description": "The exact path to the database configuration file is not specified.",
      "example": "/etc/myapp/database.yml or .env"
    },
    {
      "field": "OPERATION_SCOPE",
      "description": "The specific connection string or host parameter to change is not identified.",
      "example": "Change the 'host' field from 'old-db.example.com' to 'new-db.example.com'"
    }
  ],
  "clarification_question": "Which configuration file should be updated, and what is the exact connection parameter that needs to change?",
  "risk_note": "Modifying the wrong config file or the wrong parameter could break the database connection for all services."
}

[RISK_LEVEL]: [HIGH_RISK_FILE_OPERATIONS] require human approval before execution, even if all fields are present. These include: deletion of files outside [TEMP_DIRECTORIES], modification of [AUTHENTICATION_FILES], and any operation on [PRODUCTION_SYSTEM_PATHS].

To adapt this template, replace the square-bracket placeholders with your actual tool names, directory allowlists, protected file patterns, and risk classifications. The [OUTPUT_SCHEMA] should match the parsing logic in your application harness. If your system uses function calling instead of free-text JSON, convert the schema into a tool definition with the same required fields. The [EXAMPLES] section is critical for teaching the model the boundary between a valid request and an underspecified one—add at least three examples that cover your most common failure patterns. For high-risk environments, ensure the [RISK_LEVEL] placeholder maps to a real policy that triggers a human approval step in your harness before any tool invocation.

This prompt is a pre-execution gate, not a conversational nicety. It must be wired into the application such that the agent's file-system tool or code execution environment is unreachable until the clarification loop is resolved. The harness should treat the model's output as a structured signal: if the prompt returns a halt_and_clarify response, the application layer must block any write_file, delete_file, patch_file, or execute_command tool calls in the current turn and surface the clarification question to the user. Do not rely on the model to voluntarily skip calling a tool; the application must enforce the block by inspecting the structured output before the tool-use step.

Implement a structured output parser that expects a JSON object with a top-level decision field set to either proceed or halt_and_clarify. When halt_and_clarify is returned, the harness must extract the clarification_question string and the missing_fields array and present them to the user. The user's response should be appended to the conversation context and the prompt re-evaluated. A retry budget of 2-3 clarification rounds prevents infinite loops; if the user fails to resolve the ambiguity after the budget is exhausted, escalate to a human reviewer with the full conversation transcript. For high-risk environments, log every halt_and_clarify event with the original user request, the model's structured output, and the user's clarification response for auditability.

Model choice matters here. Use a model with strong instruction-following and structured output support (e.g., GPT-4o, Claude 3.5 Sonnet) and set temperature=0 to maximize deterministic gating behavior. The prompt template's [SAFETY_POLICY] placeholder should be populated from a configuration store, not hardcoded, so that safety rules can be updated without changing the prompt. Before deploying, build a small eval suite of 15-20 test cases covering: clear file paths with explicit operations (should proceed), missing paths (should halt), missing operations (should halt), destructive operations without confirmation (should halt), and ambiguous glob patterns (should halt). Measure both false-positive interruptions and false-negative passes; a single false negative that allows an unsafe file operation is a critical failure. Wire these evals into your CI pipeline so that any prompt or policy change is gated on passing the full safety suite.