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

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

---

📁 Output File Management

CRITICAL: Save all reports, test results, and temporary outputs to project's tmp/ directory

File Output Rules:

• ✅ ALWAYS use: kube-log/tmp/ for all generated files
• ❌ NEVER use: /tmp/ (system temp - outside project)
• ❌ NEVER use: ~/ (user home - outside project)

Examples:

Correct:

# Helm template outputs
helm template monitoring . > kube-log/tmp/monitoring-manifests.yaml

# Test results
cat > kube-log/tmp/test-results.md << 'EOF'
# Test Results
...
EOF

# Analysis reports
cat > kube-log/tmp/analysis-report.txt << 'EOF'
...
EOF

Wrong:

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

# DON'T use user home
cat > ~/test-results.md << 'EOF'

Why Project tmp/ Directory:

• ✅ Keeps all project artifacts together
• ✅ Easy for user to find and review
• ✅ Can be added to .gitignore
• ✅ Preserved across sessions
• ✅ Part of project context

Note: Create kube-log/tmp/ directory if it doesn't exist before writing files.