From b781dd8dc6230221fba2ecfd7c7c526d2b60cceb Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Wed, 3 Jun 2026 12:06:39 -0600
Subject: [PATCH] docs: improved fs_patch and fs_write descriptions and
 examples

---
 assets/agents/sisyphus/config.yaml | 4 +++-
 assets/functions/tools/fs_patch.sh | 6 ++++--
 assets/functions/tools/fs_write.sh | 4 +++-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/assets/agents/sisyphus/config.yaml b/assets/agents/sisyphus/config.yaml
index 56f0510..11c4f18 100644
--- a/assets/agents/sisyphus/config.yaml
+++ b/assets/agents/sisyphus/config.yaml
@@ -243,7 +243,9 @@ instructions: |
 
   When you write or modify files yourself (rather than delegating to coder):
 
-  - **For writing files**, ALWAYS use `fs_write` (new file / full overwrite) or `fs_patch` (surgical edit). NEVER write files via `execute_command`. Do not use:
+  - **For editing an existing file**, prefer `fs_patch`. It's a surgical edit that preserves unchanged content. Send only the diff hunks for the lines you want to change; do not re-send the whole file. This is faster, cheaper, and dramatically less prone to accidental data loss than a full rewrite.
+  - **For writing a NEW file or doing a COMPLETE rewrite**, use `fs_write`. Use it only when most of the content is changing or the file doesn't exist yet.
+  - **NEVER write files via `execute_command`.** Do not use:
     - `cat > file`, `cat >> file`, `tee`
     - `echo >`, `printf >`
     - Heredocs (`<<EOF`, `<<-EOF`, `<<'EOF'`)
diff --git a/assets/functions/tools/fs_patch.sh b/assets/functions/tools/fs_patch.sh
index 083119a..caa7165 100755
--- a/assets/functions/tools/fs_patch.sh
+++ b/assets/functions/tools/fs_patch.sh
@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 set -e
 
-# @describe Apply a patch to a file at the specified path.
-# This can be used to edit a file without having to rewrite the whole file.
+# @describe Apply a unified-diff patch to a file at the specified path. Use this for editing an existing file. It's the
+# PREFERRED way to modify a file. Prefer this over fs_write whenever the file already exists: it sends less data,
+# preserves unchanged content automatically, and is less prone to accidental data loss from full rewrites.
+# Use fs_write only when you are creating a new file or doing a complete rewrite where most of the content changes.
 
 # @option --path! The path of the file to apply the patch to
 # @option --contents! The patch to apply to the file
diff --git a/assets/functions/tools/fs_write.sh b/assets/functions/tools/fs_write.sh
index 235126f..7c18eb5 100755
--- a/assets/functions/tools/fs_write.sh
+++ b/assets/functions/tools/fs_write.sh
@@ -1,7 +1,9 @@
 #!/usr/bin/env bash
 set -e
 
-# @describe Write the full file contents to a file at the specified path.
+# @describe Write the FULL file contents to a file at the specified path. Use this for NEW files or COMPLETE rewrites
+# only. For editing an existing file, prefer fs_patch. It's a surgical edit that preserves unchanged content, requires
+# sending less data, and is less prone to accidental data loss.
 
 # @option --path! The path of the file to write to
 # @option --contents! The full contents to write to the file