ai-superpower/.ai/skills/file-editing/SKILL.md

name	description	category	impact
file-editing	Rules for sandbox file editing into tmp/ topics to avoid root pollution. Use when creating temporary files, drafts, scratchpads, or experimenting.	workflow	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:

# 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:

# 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 .gitignored, preventing accidental commits of test data.
• ✅ Easy for the user to review or delete later.