File Operations and Editing Rules

Relevant source files

• Qoder/prompt.txt
• README.md

Purpose and Scope

This document details Qoder's file operation system and the critical editing rules that govern how code modifications are performed. It covers the mandatory use of the search_replace tool, the 600-line constraints, exact whitespace matching requirements, and the $100,000,000 penalty system that enforces proper tool selection. This page focuses specifically on the mechanics of file editing; for information about code validation after edits, see Code Change Validation Pipeline; for task planning that precedes file operations, see Planning Approach and Task Breakdown.

Sources: Qoder/prompt.txt121-290

---

Available File Operation Tools

Qoder provides six file operation tools, each with specific use cases and constraints:

Tool	Purpose	Primary Use Case	Line Limit
list_dir	List directory contents	Directory exploration	N/A
read_file	Read file contents with optional dependency viewing	Mandatory pre-edit context gathering	N/A
create_file	Create new files	New file generation only	600 lines max
search_replace	Make precise string replacements in existing files	DEFAULT editing tool	600 lines total across all replacements
edit_file	Propose edits to existing files	Only when explicitly instructed	N/A
delete_file	Safely delete files	File removal	N/A

Critical Rule: The system MUST always default to using search_replace for editing existing files unless explicitly instructed to use edit_file, or face a $100,000,000 penalty.

Sources: Qoder/prompt.txt302-309 Qoder/prompt.txt236-243 Qoder/prompt.txt359-365

---

File Operation Tool Ecosystem

Sources: Qoder/prompt.txt302-320 Qoder/prompt.txt146-150

---

The Read-Before-Write Mandate

Universal Rule: Qoder MUST read a file's contents before attempting any modifications. This is non-negotiable across all file editing operations.

Workflow Sequence

1. Gather Context: Use read_file to load the target file into context
2. Identify Target: Locate the exact text to be modified
3. Prepare Replacement: Construct the new content
4. Execute Edit: Call search_replace with exact original text and new text
5. Validate: Run get_problems to verify no issues introduced

Why This Is Critical

• Uniqueness Verification: Ensures the original_text parameter uniquely identifies the target location
• Whitespace Accuracy: Allows exact matching of indentation and formatting
• Context Awareness: Prevents modifications to wrong locations with similar code
• Dependency Detection: Optional dependency viewing reveals import/usage relationships

Sources: Qoder/prompt.txt121-124 Qoder/prompt.txt359-365

---

Primary Editing Tool: search_replace

The search_replace tool is Qoder's default and strongly preferred method for modifying existing files. It performs precise string replacement operations with exact matching semantics.

Core Parameters

search_replace(
    path: string,              // File path to edit
    original_text: string,     // Exact text to find (must be unique)
    new_text: string           // Replacement text
)

Critical Requirements

Requirement	Description	Penalty for Violation
Default Tool	Must use search_replace unless explicitly told otherwise	$100,000,000
Unique Match	original_text must uniquely identify target location	$100,000,000
Exact Whitespace	Must match all spaces, tabs, newlines precisely	$100,000,000
No Identity	original_text and new_text cannot be identical	$100,000,000
Line Limit	Total lines across all replacements < 600	$100,000,000
No Whole File	DO NOT replace entire file content	$100,000,000

Example Usage Pattern

Sources: Qoder/prompt.txt236-243 Qoder/prompt.txt122-124 Qoder/prompt.txt359-365

---

The // ... existing code ... Pattern

To minimize token usage and focus on actual changes, Qoder uses a special comment pattern to represent unchanged code sections between modifications.

Pattern Format

// ... existing code ...
FIRST_EDIT
// ... existing code ...
SECOND_EDIT
// ... existing code ...

Usage Guidelines

1. Minimize Unchanged Code: Only include enough context to uniquely identify the location
2. Show Boundaries: Use the pattern to indicate where unchanged code exists
3. Multiple Edits: Use the pattern between multiple modifications in the same file
4. Language Agnostic: Adapt the comment syntax to the file's language (e.g., # ... existing code ... for Python)

Example: Python File Edit

This pattern clearly shows the new process_user function is being inserted between existing code blocks without cluttering the replacement with unnecessary context.

Sources: Qoder/prompt.txt134-143

---

Whitespace and Exact Matching Requirements

The search_replace tool requires byte-for-byte exact matching of the original_text parameter, including all whitespace characters.

Matching Rules

Element	Requirement
Spaces	Exact count and position
Tabs	Must match tab characters exactly (not converted to spaces)
Newlines	Line break positions must match precisely
Indentation	Leading whitespace must be identical
Trailing Whitespace	Trailing spaces/tabs at line ends must match

Common Pitfalls

Verification Strategy

1. Copy Exact Text: When reading the file, copy the exact text block including all whitespace
2. Visual Inspection: Check indentation levels match the file
3. Character Counting: Count spaces/tabs to verify accuracy
4. Test Match: Ensure the original_text appears exactly once in the file

Sources: Qoder/prompt.txt242-243

---

Line Count Constraints

Qoder enforces strict line count limits on file operations to manage token usage and maintain operational efficiency.

Limits by Tool

Constraint Details

Tool	Limit Type	Limit Value	Counted Elements
create_file	Per file	600 lines	Total lines in new file
search_replace	Per call	600 lines	Sum of all new_text line counts across all replacements in single call

Handling Large Changes

For modifications exceeding 600 lines:

1. Break Into Multiple Calls: Split the edit across multiple sequential search_replace calls
2. Maximize Per Call: Include as many replacements as possible within the 600-line budget
3. Sequential Execution: Execute calls sequentially (never parallel)
4. Validation Between Calls: Optionally run get_problems between calls for safety

Split Strategy Prohibition

CRITICAL: Never split short modifications (combined length under 600 lines) into several consecutive calls, OR face a $100,000,000 penalty.

This means:

• DO: Single call for 500 lines of changes
• DON'T: Split 500 lines into 5 calls of 100 lines each
• Reason: Inefficiency penalty for unnecessary fragmentation

Sources: Qoder/prompt.txt252-257 Qoder/prompt.txt240

---

The $100,000,000 Penalty System

Qoder uses an extreme penalty system ($100,000,000) to enforce critical file editing rules. This is not a literal monetary penalty but a conceptual enforcement mechanism that makes certain violations effectively impossible.

Penalty Triggers

The Six Cardinal Violations

1. Wrong Tool Selection: Using edit_file when search_replace should be default
2. Whole File Replacement: Attempting to replace entire file content with new content
3. Unnecessary Splitting: Dividing modifications under 600 lines into multiple calls
4. Non-Unique Match: original_text appears multiple times or doesn't exist
5. Whitespace Mismatch: Spaces, tabs, newlines don't match exactly
6. Identity Replacement: original_text and new_text are identical strings

Enforcement Philosophy

The $100M penalty serves to:

• Prioritize Correctness: Make precision more important than speed
• Prevent Carelessness: Force careful attention to matching requirements
• Enforce Best Practices: Ensure search_replace is used properly
• Signal Criticality: Communicate that these rules are non-negotiable

Sources: Qoder/prompt.txt236-243

---

Sequential vs Parallel Execution

File editing operations MUST ALWAYS be executed sequentially. Parallel execution of file edits is strictly prohibited with the same $100M penalty enforcement.

Execution Rules by Operation Type

Operation Type	Parallel Allowed?	Rationale
File Reading (read_file)	✅ YES	Read-only, no conflicts
Directory Listing (list_dir)	✅ YES	Read-only, no conflicts
Code Search (search_codebase, grep_code)	✅ YES	Read-only, no conflicts
File Editing (search_replace, edit_file)	❌ NO	Prevents race conditions and consistency issues
File Creation (create_file)	❌ NO	Prevents conflicts in file system state
Terminal Commands (run_in_terminal)	❌ NO	Ensures proper execution order

Why File Edits Must Be Sequential

Consequences of Parallel File Edits

1. Race Conditions: Multiple edits to related files may conflict
2. Inconsistent State: Temporary inconsistency between file contents
3. Validation Impossibility: Cannot validate mid-edit state
4. Debugging Difficulty: Hard to trace which edit caused issues
5. System Instability: File system locks and conflicts

Parallel Operations That ARE Allowed

While file edits must be sequential, these operations can and should be parallelized for efficiency:

Sources: Qoder/prompt.txt66-80 Qoder/prompt.txt258-262

---

Tool Selection Decision Tree

Sources: Qoder/prompt.txt236-243 Qoder/prompt.txt359-365 Qoder/prompt.txt146-150

---

Validation After Edits

After ANY file editing operation, regardless of size or perceived simplicity, Qoder MUST call get_problems to validate the changes.

Mandatory Validation Workflow

1. Execute Edit: Complete the search_replace, edit_file, or create_file operation
2. Immediate Validation: Call get_problems without delay
3. Review Results: Check for compilation errors, lint warnings, type errors
4. Iterative Fixing: If issues found, fix them with additional edits
5. Re-validate: Call get_problems again after fixes
6. Continue Until Clean: Repeat until get_problems returns no issues

Validation Enforcement

From Qoder/prompt.txt146-150:

3. MANDATORY FINAL STEP:
   After completing ALL code changes, no matter how small or seemingly 
   straightforward, you MUST:
   - Use get_problems to validate the modified code
   - If any issues are found, fix them and validate again
   - Continue until get_problems shows no issues

Why This Is Non-Negotiable

Reason	Explanation
Syntax Errors	Catch typos and malformed code immediately
Type Errors	Detect type mismatches in statically-typed languages
Import Issues	Identify missing imports or circular dependencies
Lint Violations	Maintain code quality standards
Immediate Feedback	Fix issues before they cascade to dependent code

Sources: Qoder/prompt.txt146-150 Qoder/prompt.txt196-203

---

File Editing Workflow Summary

Complete End-to-End Process

Key Principles Recap

1. Default Tool: Always use search_replace unless explicitly told otherwise
2. Read First: Always call read_file before editing
3. Exact Match: Match whitespace, indentation, and formatting precisely
4. Line Limits: Stay under 600 lines per operation
5. Sequential Only: Never parallelize file edits
6. Validate Always: Call get_problems after every edit
7. Iterate to Clean: Fix and re-validate until no issues remain
8. Penalty Awareness: The $100M penalty enforces all critical rules

Sources: Qoder/prompt.txt121-290