WI-001: File Management¶

ID: WI-001
Version: 1.0
Effective Date: 2026-02-09
Owner: Infrastructure Team (Paul)
Applies To: All agents

Purpose¶

Prevent file duplication, ensure single source of truth, and maintain clean workspace structure by following consistent file management practices.

Lesson learned: Previous SOUL.md update created copies in wrong structure, leaving duplicates.

Scope¶

When to use this WI: - Updating existing files - Creating new files - Moving or renaming files - Creating backups

When NOT to use: - Temporary scratch files (use /tmp/ or clearly mark as temp) - Session-specific logs (auto-managed by OpenClaw)

Core Principles¶

Single Source of Truth — One authoritative copy, not multiple versions
Copy and Archive — Create new version at canonical location, move original to ~/archive/
Structured Archive — Old versions go to ~/archive/ with dated subfolders
Clean Up After Yourself — Remove temp files, verify no duplicates remain

Procedure¶

Step 1: Before Modifying a File - Understand Current Structure¶

Action: Check where the file lives and if other copies exist.

# Find all instances of a file
find /home/skai8888/.openclaw -name "SOUL.md" 2>/dev/null

# Check if it's under version control
cd /path/to/file
git status

Verification: - You know the canonical location (source of truth) - You know if duplicates exist (and why) - You know if it's version controlled

Step 2: Decide - Minor Edit vs Major Change¶

Scenario	Action	Example
Minor edits (typo, formatting)	Edit the file directly	Fix typo in SOUL.md
Major rewrite or structural change	Copy new version to canonical location, move original to `~/archive/`	Rewrite SOUL.md
New version replaces old	Copy new to canonical location, move old to `~/archive/`	Policy v2.0

Default: Copy and archive. For trivial edits, direct edit is fine (git has history).

Step 3: Create Backup (if significant change)¶

When backup is required: - Major rewrite - Structural changes - Requested by human - Policy/compliance documents

How to create backup:

# In the same directory, with timestamp
cp SOUL.md SOUL.md.backup-$(date +%Y%m%d-%H%M%S)

For version-controlled files:

# Git handles backups, just commit before changes
git add SOUL.md
git commit -m "Pre-update backup: [describe what you're about to change]"

Verification: - Backup file exists - Backup has timestamp or git commit reference - Original file still intact

Step 4: Make the Change¶

Action: Update the file in place.

# Use appropriate tool
nano SOUL.md
# or
echo "new content" >> SOUL.md

Verification: - Changes applied correctly - File still in original location - No duplicate copies created

Step 5: Clean Up¶

Action: Remove temporary files, move backups to appropriate location.

For backups:

# If short-term backup (testing only), delete after verification
rm SOUL.md.backup-20260209-143000

# If long-term backup (archive), move to archive
mv SOUL.md.backup-20260209-143000 /home/skai8888/.openclaw/archive/agent-souls/2026-02-09/

For temp files:

# Remove temp files
rm /tmp/scratch-*
rm *.tmp

Verification: - No duplicate copies in working directory - Backups in appropriate location (archive or deleted) - No temp files left behind

Step 6: Document the Change¶

For significant changes:

# Git commit
git add SOUL.md
git commit -m "Updated SOUL.md: [what changed and why]"

# Or update memory
echo "$(date +%Y-%m-%d): Updated SOUL.md - [reason]" >> memory/$(date +%Y-%m-%d).md

Verification: - Change is documented - Future you knows why the change was made

Quality Checks¶

Before considering the task complete:

[ ] Original file updated (not replaced with new copy)
[ ] Backup created (if significant change)
[ ] No duplicate copies in working directory
[ ] Temp files removed
[ ] Change documented (git commit or memory log)
[ ] Verified file still works (e.g., agent loads SOUL.md correctly)

Common Mistakes & How to Avoid Them¶

❌ Mistake 1: Creating copies instead of updating¶

Bad:

cp SOUL.md SOUL-new.md
nano SOUL-new.md
# Now you have two files, which is source of truth?

Good:

cp SOUL.md SOUL.md.backup-20260209
nano SOUL.md
# Original file is source of truth, backup for safety

❌ Mistake 2: Random backup locations¶

Bad:

cp SOUL.md /home/skai8888/.openclaw/workspace/Dev-Ops/projects/some-project/SOUL-backup.md
# Scattered backups everywhere

Good:

cp SOUL.md /home/skai8888/.openclaw/archive/agent-souls/2026-02-09/Maya-SOUL.md
# Centralized archive location

❌ Mistake 3: Forgetting to clean up¶

Bad:

nano SOUL.md.draft
# Leave draft file forever

Good:

nano SOUL.md.draft
cp SOUL.md.draft SOUL.md
rm SOUL.md.draft
# Cleaned up after yourself

❌ Mistake 4: No documentation¶

Bad:

nano SOUL.md
# What changed? Why? No idea.

Good:

git commit -m "Updated SOUL.md: Added finance expertise to Maya's role (per CEO request)"
# Future you knows exactly what happened

Troubleshooting¶

Problem: I accidentally created a duplicate file.
Solution: 1. Identify which is the source of truth 2. Move the duplicate to archive or delete it 3. Document which file is canonical in memory

Problem: I don't know if this change is "significant" enough for a backup.
Solution: - If unsure, create backup (cheap insurance) - Rule of thumb: If you'd be upset to lose the current version, back it up

Problem: The file is in Git, do I still need manual backups?
Solution: - No, git commit before changes = automatic backup - Manual backup only if you want extra safety before major rewrite

Problem: I updated the wrong file (edited a backup instead of the original).
Solution: 1. Compare the files: diff original.md backup.md 2. Copy your changes to the correct file 3. Delete the mistakenly edited backup 4. Document the mistake in memory (learn from it)

Examples¶

Example 1: Minor Edit (No Backup Needed)¶

Task: Fix typo in Maya's SOUL.md

cd /home/skai8888/.openclaw/agents/Maya/workspace/
nano SOUL.md
# Fix typo: "stratetgy" → "strategy"
git add SOUL.md
git commit -m "Fixed typo in SOUL.md"

✅ Quick, clean, no backup needed for tiny change.

Example 2: Major Rewrite (Backup Required)¶

Task: Restructure Maya's SOUL.md to new format

cd /home/skai8888/.openclaw/agents/Maya/workspace/
git add SOUL.md
git commit -m "Pre-rewrite backup: Current SOUL.md before restructuring"
nano SOUL.md
# Major edits
git add SOUL.md
git commit -m "Restructured SOUL.md: New format per WI-004"

✅ Git handles backup, changes documented.

Example 3: Archiving Old Version¶

Task: Replace old policy v1.0 with v2.0, keep old for reference

cd /home/skai8888/.openclaw/workspace/Tech-Pub/docs/governance-management/policies-procedures/
mv agent-governance-policy.md /home/skai8888/.openclaw/archive/policies/2026-02-09/agent-governance-policy-v1.0.md
cp /path/to/new/agent-governance-policy-v2.0.md agent-governance-policy.md
git add agent-governance-policy.md
git commit -m "Replaced agent-governance-policy with v2.0 (v1.0 archived)"

✅ Old version preserved, new version in canonical location.

Version History¶

Version	Date	Author	Changes
1.0	2026-02-09	Main Agent	Initial version (lesson learned from SOUL.md mess)

WI-001: File Management¶

Purpose¶

Scope¶

Core Principles¶

Procedure¶

Step 1: Before Modifying a File - Understand Current Structure¶

Step 2: Decide - Minor Edit vs Major Change¶

Step 3: Create Backup (if significant change)¶

Step 4: Make the Change¶

Step 5: Clean Up¶

Step 6: Document the Change¶

Quality Checks¶

Common Mistakes & How to Avoid Them¶

❌ Mistake 1: Creating copies instead of updating¶

❌ Mistake 2: Random backup locations¶

❌ Mistake 3: Forgetting to clean up¶

❌ Mistake 4: No documentation¶

Troubleshooting¶

Examples¶

Example 1: Minor Edit (No Backup Needed)¶

Example 2: Major Rewrite (Backup Required)¶

Example 3: Archiving Old Version¶

Related Documents¶

Version History¶