Safe Search-and-Replace Prompt Template

This prompt is designed for AI coding agents that need to perform a single, unambiguous text replacement within a known file. The core job-to-be-done is a surgical edit: given a specific instruction like 'rename the function getCwd to getCurrentWorkingDirectory in src/utils.py', the agent must produce a verifiable plan before acting. The ideal user is a developer or an AI engineer integrating a coding agent into a product where edit precision is non-negotiable. Required context includes the exact file path, the precise string to find, and the exact replacement string. Without this context, the prompt cannot enforce its primary guardrail: an exact-match uniqueness check.

Use this prompt when the edit instruction is concrete and the target location is known. It is the right tool for renaming a single symbol, updating a hardcoded value, or fixing a specific typo. The prompt forces the agent to output a plan containing the exact match string, a confirmation that the string appears exactly once in the file, and a dry-run diff. This prevents the agent from making blind, ambiguous, or scattershot edits that corrupt a codebase. For example, if you ask an agent to 'update the API version to v2', this prompt will force it to locate the single line where the version is defined, confirm no other occurrences exist, and show you the one-line change before it is applied.

Do not use this prompt for multi-file refactors, fuzzy find-and-replace, or generating new code blocks. It is explicitly not designed for tasks like 'update all error handling to use the new Result type across the project' or 'add a new endpoint to the controller.' Those tasks require a different class of prompts focused on patch planning, multi-file edit consistency, and impact scope analysis. Using this prompt for broad changes will result in a failed uniqueness check, causing the agent to halt and request more specific instructions. The next step after reading this section is to review the prompt template itself and understand how to wire the exact-match and dry-run constraints into your agent's execution loop.

This prompt template instructs a coding agent to perform a safe search-and-replace operation on a specified file. It requires the agent to locate the exact match string, verify uniqueness, produce a dry-run diff, and only apply the change after confirming no unintended matches exist. Use this template when you need a single, auditable text replacement with built-in safety checks—not for multi-file refactors or complex AST transformations.

textCopy
You are a coding agent performing a safe search-and-replace operation. Follow these steps in order and stop if any check fails.

## Inputs
- File path: [FILE_PATH]
- Search string (exact match): [SEARCH_STRING]
- Replacement string: [REPLACEMENT_STRING]
- Expected match count: [EXPECTED_MATCH_COUNT]
- Context lines before match (optional): [CONTEXT_BEFORE]
- Context lines after match (optional): [CONTEXT_AFTER]

## Constraints
- [CONSTRAINTS]

## Procedure
1. Read the file at [FILE_PATH] and compute its SHA-256 hash. Record this as the pre-edit hash.
2. Search for [SEARCH_STRING] as an exact substring match. Count all occurrences.
3. If the match count does not equal [EXPECTED_MATCH_COUNT], stop and report the discrepancy. Include line numbers for every match found.
4. If [CONTEXT_BEFORE] or [CONTEXT_AFTER] are provided, verify that the surrounding lines of the target match contain the specified context. Stop if context verification fails.
5. Generate a unified diff showing the proposed change. This is the dry-run diff. Do not modify the file yet.
6. Review the dry-run diff for unintended changes, whitespace noise, or scope creep. If any issue is found, stop and report it.
7. If all checks pass, apply the replacement and write the file.
8. Compute the SHA-256 hash of the modified file. Record this as the post-edit hash.
9. Verify that the replacement appears exactly once in the modified file (or [EXPECTED_MATCH_COUNT] times if replacing all occurrences).
10. Generate a reverse patch that restores the original content and verify it applies cleanly.

## Output Schema
Return a JSON object with this structure:
{
  "file_path": "string",
  "pre_edit_hash": "string",
  "post_edit_hash": "string",
  "match_count_found": number,
  "match_count_expected": number,
  "context_verified": boolean,
  "dry_run_diff": "string (unified diff format)",
  "applied": boolean,
  "reverse_patch": "string (unified diff format)",
  "reverse_patch_verified": boolean,
  "errors": ["string"]
}

## Risk Level
[RISK_LEVEL]

Adapt this template by filling each square-bracket placeholder with concrete values. For [CONSTRAINTS], add file-specific rules such as 'do not modify lines containing import statements' or 'preserve trailing commas.' Set [RISK_LEVEL] to 'low', 'medium', or 'high' to control whether the agent should escalate for human review before applying changes. For high-risk files, pair this prompt with a human-in-the-loop handoff that presents the dry-run diff for approval. Always test this prompt against a copy of the target file first, and validate that the reverse patch restores the original content exactly before trusting it in automated pipelines.

The Safe Search-and-Replace prompt is designed to be called as a single step within a larger agent loop, not as a standalone chat interaction. Your application should invoke this prompt when a coding agent has determined that a targeted text replacement is the correct action. The prompt expects a structured input payload containing the file path, the current file content, the replacement intent, and any constraints such as uniqueness requirements or scope boundaries. Do not call this prompt for multi-file refactors, wholesale rewrites, or cases where the replacement target cannot be expressed as an exact string match. Those scenarios require the Patch Planning or Multi-File Edit Consistency prompts instead.

Wire the prompt into your agent harness with a pre-invocation validation layer. Before calling the model, verify that the file exists, that the current content hash matches the hash provided in the input, and that the file is not on a deny list of generated or vendor-managed paths. After receiving the model's structured output, parse the replacement plan and run automated checks: confirm that every search string appears exactly once in the target file, that no search string is a substring of another search string, and that the proposed replace text does not introduce syntax errors for the file type. For high-risk files such as production configuration, security policies, or database migration scripts, route the replacement plan to a human approval queue before any file modification occurs. Log the full prompt input, model output, validation results, and approval decision to your audit trail.

Apply the replacement using a transactional file operation: write the modified content to a temporary file, compute its hash, and only atomically replace the original file after confirming the write succeeded. Immediately run a post-edit verification by calling the Post-Edit Diff Verification prompt, comparing the actual diff against the expected change. If the diff contains unintended modifications, whitespace noise, or scope creep beyond the declared replacement, invoke the Rollback Decision prompt to determine whether to revert, retry with tighter constraints, or escalate. For batch replacements across multiple files, serialize the operations and verify each file individually before proceeding to the next. Never apply a second replacement until the first file's verification passes. The most common production failure mode is a search string that matches zero or multiple locations due to file drift between the snapshot and the edit attempt—always gate on exact match uniqueness before touching the file.