---
name: file-editing
description: Rules for sandbox file editing into tmp/ topics to avoid root pollution. Use when creating temporary files, drafts, scratchpads, or experimenting.
category: workflow
impact: low
---

# File Editing Instructions

## 🛠️ FILE EDITING RULES - CRITICAL

**NEVER EVER modify files using terminal commands. NO EXCEPTIONS.**

### Forbidden Commands - DO NOT RUN:
1. ❌ `cat > file.txt` - Creates/overwrites file
2. ❌ `cat >> file.txt` - Appends to file
3. ❌ `cat << EOF > file.txt` - Here-document to file
4. ❌ `echo "text" > file.txt` - Writes to file
5. ❌ `echo "text" >> file.txt` - Appends to file
6. ❌ `sed -i` - In-place file modification
7. ❌ `awk` - Any file modification
8. ❌ `perl -i` - In-place file modification
9. ❌ `tee` - Writing to files
10. ❌ `>` or `>>` redirect operators - Any file writing
11. ❌ `<< EOF` - Here-documents to files
12. ❌ **ANY command that writes to, modifies, or creates files**

### ONLY use tools for file modifications:
- ✅ `create_file` - Creating new files
- ✅ `replace_string_in_file` - Editing existing files
- ✅ `multi_replace_string_in_file` - Multiple edits efficiently
- ✅ User sees exact changes in UI
- ✅ Can approve or reject each edit
- ✅ Clear diff of what changes
- ✅ Trackable and reviewable

**Terminal commands ONLY for:**
- Read-only operations (`grep`, `find`, `cat`, `less`, `head`, `tail`)
- Helm commands (`helm template`, `helm show`)
- Git read operations (`git diff`, `git status`, `git log`)
- Analysis commands that don't modify files

---

## Why This Rule Exists

- User must see and approve all file changes
- Terminal file modifications bypass VS Code diff UI
- No audit trail for terminal-based edits
- High risk of accidental overwrites
- Production infrastructure requires careful change control

---

## 📁 Scratch and Temporary Files (Testing, Terminal outputs, Work drafts)

**CRITICAL: NEVER create temporary, testing, or intermediate files in the project root or source directories.** 

All scratch work, terminal outputs, test scripts, and experimental code MUST be created in the project's `tmp/` directory using a specific structure:

```
tmp/<topic>/<title>.<extension>
```

- **`topic`**: A short, hyphenated slug describing the feature, bug, or task you are working on (e.g., `auth-flow-tests`, `db-migration`).
- **`title`**: What the file actually contains (e.g., `curl-test`, `raw-manifest`).
- **`<extension>`**: The appropriate file extension for the content (e.g., `.sh`, `.json`, `.yaml`, `.py`).

### File Output Rules:
- ✅ **ALWAYS use topic subfolders:** `tmp/<topic>/<filename>` for all generated temporary files, scripts, and logs.
- ❌ **NEVER use `tmp/` root:** Do NOT create files directly under `tmp/` (e.g., `tmp/test.sh`). The folder will bloat and become impossible to navigate.
- ❌ **NEVER use Project root:** (e.g., `./test.py`, `./output.txt`).
- ❌ **NEVER use System `/tmp/` or user home `~/`:** (They are outside project context and invisible to the user).

### Examples:

**Correct:**
```bash
# Helm template outputs
helm template monitoring . > tmp/monitoring-setup/rendered-manifests.yaml

# Temporary test scripts
create_file("tmp/auth-flow/test-token.sh", "...")

# JSON payload for curl
create_file("tmp/payment-api/test-payload.json", "...")
```

**Wrong:**
```bash
# DON'T write to project root!
helm template monitoring . > rendered-manifests.yaml
create_file("test-token.sh", "...")

# DON'T use system /tmp
helm template monitoring . > /tmp/monitoring-manifests.yaml
```

### Why use `tmp/<topic>/`:
- ✅ Keeps the project root clean.
- ✅ Groups related investigation files together by topic.
- ✅ The entire `tmp/` folder is `.gitignore`d, preventing accidental commits of test data.
- ✅ Easy for the user to review or delete later.