python-large-file-patch-{{AGENT_NAME_LOWER}}

Skill: Patching Large Python Files in {{AGENT_NAME}}

When to Use

When you need to edit a specific function or code block inside a large Python file (500+ lines) in the {{AGENT_NAME}} codebase (signal_processor.py, run_agent.py, gateway/run.py, etc.), and direct patch fails due to text pattern mismatch.

The Problem

patch relies on exact string matching. Large files with complex docstrings (especially with newlines and special characters) often don't match what you expect from reading partial snippets. You get "old_string not found" even when the function exists.

CRITICAL: Dual-File Layout (Runtime vs Source)

{{AGENT_NAME}} has two copies of the agent code:

Copy	Path	Purpose
Runtime	~/.{{AGENT_NAME_LOWER}}/agent/	What Python actually imports at runtime
Source	~/.{{AGENT_NAME_LOWER}}/source/{{AGENT_NAME_LOWER}}-agent/agent/	Git-tracked development copy

When you patched a file in the source/ copy but nothing changed, it's because Python loaded from ~/.{{AGENT_NAME_LOWER}}/agent/ instead. The two copies can and do diverge.

Patching Protocol

1. Identify which copy is live before editing:

   python3 -c "import module_name; print(module_name.__file__)"
   

2. Patch the runtime copy first (~/.{{AGENT_NAME_LOWER}}/agent/...) — that's where the effect is immediate.

3. Sync the source copy after the fix to keep them aligned:

   cp ~/.{{AGENT_NAME_LOWER}}/agent/patched_file.py ~/.{{AGENT_NAME_LOWER}}/source/{{AGENT_NAME_LOWER}}-agent/agent/patched_file.py
   

4. Verify with an import and test call before declaring done.

Solution: Python Patch Script with Diagnostic Output

When patch fails, use execute_code to:

1. First read the file and locate the exact text with in operator
2. Print diagnostics so you know exactly what to match
3. Apply with content.replace(old, new, 1) — the 1 limit prevents accidental multi-match
4. Write back and verify