Code Editing and Validation Workflow

Relevant source files

• Same.dev/Prompt.txt

Purpose and Scope

This document describes Same.dev's code editing and validation workflow, covering tool selection logic, pre-edit requirements, validation procedures, and error handling mechanisms. This page focuses specifically on the mechanics of making code changes and ensuring they are error-free before delivery to the user.

For information about parallel tool execution strategy across multiple files, see Tool Execution and Parallel Processing. For web development best practices including framework-specific configurations, see Web Development Best Practices.

Tool Selection Strategy

Same.dev provides two distinct tools for code modification: edit_file and string_replace. The selection between these tools follows a clear decision tree based on file size and edit scope.

Decision Logic: edit_file vs string_replace

The primary selection criterion is file size, with a threshold of 2500 lines determining tool choice:

Condition	Selected Tool	Rationale
File > 2500 lines AND small edit	string_replace	Efficient for targeted changes in large files
File ≤ 2500 lines	edit_file	Preferred for most edits with intelligent apply model
New file creation	Either (context dependent)	Both tools support file creation

The edit_file tool is the default preference for the majority of editing scenarios due to its intelligent apply model that understands code structure and context.

Decision Tree Diagram

Sources: Same.dev/Prompt.txt238-239

smart_apply Retry Mechanism

When the edit_file tool's apply model fails to follow a reasonable code_edit suggestion, the system implements a retry mechanism using the smart_apply parameter:

The smart_apply parameter activates enhanced code understanding in the apply model, improving its ability to correctly interpret and execute the intended edit.

Sources: Same.dev/Prompt.txt239-240

Pre-Edit Requirements

Mandatory Read-Before-Write Rule

Same.dev enforces a strict read-before-write requirement for nearly all editing operations:

Rule: Unless appending a small, easy-to-apply edit to a file or creating a new file, the agent MUST read the contents or section being edited before making modifications.

Exceptions:

1. Small append operations (adding content to end of file)
2. New file creation
3. Trivial edits with complete context already available

Rationale: This requirement ensures the agent has accurate context about:

• Current code structure and formatting
• Existing imports and dependencies
• Variable names and function signatures
• Code style and patterns

Workflow Integration

Sources: Same.dev/Prompt.txt235-236

Context Gathering

Before editing, the agent typically performs parallel read operations to gather comprehensive context:

• File content: Read target file(s) using read_file
• Related files: Identify and read imported modules or dependencies
• Configuration: Review relevant config files (package.json, tsconfig.json, etc.)

This context gathering leverages Same.dev's parallel execution capability to minimize latency (see Tool Execution and Parallel Processing).

Sources: Same.dev/Prompt.txt70-71 Same.dev/Prompt.txt235-236

Validation Pipeline

run_linter Tool Execution

The run_linter tool is a mandatory component of Same.dev's code quality assurance system:

Invocation Points:

1. After every significant edit
2. Before each version creation

Purpose: Detect linting errors, type errors, and other runtime issues before they reach the user.

Sources: Same.dev/Prompt.txt237-238

Iterative Fixing Loop

When run_linter detects errors, the agent enters an iterative fixing loop:

Loop Logic:

1. Analyze linter output
2. Determine if fix is clear and straightforward
3. If clear: Apply fix and re-run linter
4. If unclear: Do NOT make uneducated guesses
5. Track loop iterations

Fix Criteria:

• Fix must be clear and obvious from error message
• Agent must be certain it can solve the problem (see debugging guidance)
• No speculative changes allowed

Sources: Same.dev/Prompt.txt237-238

3-Attempt Circuit Breaker

Same.dev implements a circuit breaker pattern to prevent infinite fixing loops:

Circuit Breaker Rules:

Iteration	Action	Outcome
Attempt 1	Apply fix, run linter	Continue if errors remain
Attempt 2	Apply fix, run linter	Continue if errors remain
Attempt 3	Apply fix, run linter	STOP regardless of outcome
After 3	Stop and ask user what to do next	Escalation path

Escalation Options Presented to User:

1. User provides additional guidance
2. User chooses to revert (using Rollback/Revert buttons)
3. User contacts Same support at [email protected]

Circuit Breaker State Machine

This circuit breaker prevents resource waste and user frustration from repeated failed fix attempts on the same file.

Sources: Same.dev/Prompt.txt237-238

Error Prevention Standards

Error-Free Code Requirement

Same.dev mandates that all generated code must be runnable immediately by the user without errors:

Critical Requirements:

1. Include all necessary import statements
2. Include all necessary dependencies
3. Include all required endpoints for the code to function

Code Generation Restrictions:

Prohibited Content	Rationale
Extremely long hashes	Not helpful, expensive to generate
Binary data	Cannot be run as code, expensive
.ico files	Non-textual, expensive
Other non-textual content	General prohibition on non-runnable content

These restrictions prevent the generation of content that appears to be code but cannot be executed or validated.

Sources: Same.dev/Prompt.txt67-69 Same.dev/Prompt.txt232-234

Import and Dependency Management

The agent must proactively ensure all code dependencies are satisfied:

Import Statement Requirements:

• Every external library reference requires corresponding import
• Import paths must be correct relative to file structure
• Import style must match existing codebase conventions

Dependency Installation:

• Use bun add for package installation (not npm)
• Verify dependencies exist in package.json after installation
• Consider version compatibility with existing packages

Sources: Same.dev/Prompt.txt67 Same.dev/Prompt.txt232

Sequential vs Parallel Execution Context

While Same.dev strongly emphasizes parallel tool execution (see Tool Execution and Parallel Processing), code editing operations have specific sequencing requirements:

Edit Operations That MUST Be Sequential:

1. Read → Edit sequence for same file
2. Edit → Validate (run_linter) sequence
3. Multiple edits to same file (cannot parallelize)
4. Validate → Fix → Re-validate loop

Operations That CAN Be Parallel:

1. Reading multiple files for context
2. Editing different files simultaneously
3. Multiple linter runs on different files

Example Workflow

The parallel read phase maximizes efficiency (3-5x faster), while the sequential edit-validate phase ensures correctness.

Sources: Same.dev/Prompt.txt45-49 Same.dev/Prompt.txt210-214

Complete Workflow State Machine

The following diagram illustrates the complete state machine for Same.dev's code editing and validation workflow, integrating all components:

This state machine encompasses:

• Exception handling for read-before-write rule
• Tool selection logic with file size thresholds
• smart_apply retry mechanism
• Validation with run_linter
• Iterative fixing with circuit breaker
• User escalation paths

Sources: Same.dev/Prompt.txt62-75 Same.dev/Prompt.txt227-240

Key Implementation Parameters

The following table summarizes the key parameters and thresholds governing Same.dev's editing workflow:

Parameter	Value	Purpose
File size threshold	2500 lines	Determines edit_file vs string_replace
Circuit breaker limit	3 attempts	Maximum fixing iterations per file
required_param: relative_file_path	First argument	Tool parameter ordering requirement
smart_apply parameter	Boolean	Retry mechanism for edit_file
Validation trigger	"significant edit"	When to invoke run_linter
Parallel edit constraint	Same file: NO	Prevent concurrent same-file edits
Read requirement	Pre-edit	Must read before editing (with exceptions)

Sources: Same.dev/Prompt.txt62-75 Same.dev/Prompt.txt227-240