---
roadcrew_template_name: "update-my-documents.md"
roadcrew_template_type: "command"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
execution_mode: "auto-execute"
---

# update-my-documents

Update current memory bank documents (activeContext.md, progress.md, systemPatterns.md).

> **Execution:** Runs immediately with automatic batching. No approval needed.

**Context:** Run this when you've completed significant work and want to capture learnings.

<!-- Usage: /update-my-documents [document-type] -->

You are upgrading instance repository documents to use the latest template structures.

**Document Types:**
- `vision` - Upgrade memory-bank/activeContext.md (if not already migrated from context/vision.md)
- `spec` - Upgrade context/specs/*.md files
- `current-release` - Upgrade memory-bank/releases/current-release.md
- `future-releases` - Upgrade memory-bank/releases/future-releases.md
- `minor-release` - Upgrade memory-bank/releases/minor-release.md
- `all` - Upgrade all documents

MANDATORY CURSOR RULES COMPLIANCE: All changes must align with `.cursor/rules/` standards

## Overview

This command performs **non-destructive template migrations** to upgrade existing documents to new template structures while preserving all content.

**Why this matters:**
- Platform templates improve over time (new sections, better structure)
- Instance repos need to benefit from improvements
- Manual migration is error-prone and time-consuming
- Automated migration prevents content loss

## Workflow

### 0. EXPLAIN AND CONFIRM

**Before any changes:**
```
This will upgrade your documents to the latest template versions:

Documents to upgrade:
- memory-bank/activeContext.md (v1.0 → v2.0)
  * New: Business Outcomes, Capability Ladder, Strategic Position

Changes will:
✅ Preserve all your existing content
✅ Add new sections with {{PLACEHOLDER}} markers  
✅ Create backup files (.backup-YYYY-MM-DD)
✅ Show diff before saving
✅ Update template_version metadata

Proceed with upgrade? (yes/no)
```

**User must type `yes` to continue. If `no`, exit gracefully.**

### 1. DETECT CURRENT STATE

For each document to upgrade:

**A) Check if file exists:**
```bash
if [ ! -f "memory-bank/activeContext.md" ]; then
  echo "File not found. Create it first using templates/vision.template.md"
  exit 1
fi
```

**B) Read template version from frontmatter:**
```bash
# Look for YAML frontmatter at start of file
CURRENT_VERSION=$(head -20 "$FILE" | grep "template_version:" | sed 's/template_version: "//' | sed 's/"$//')

if [ -z "$CURRENT_VERSION" ]; then
  echo "No template_version found. Detecting based on structure..."
  # Analyze structure to infer version
  if grep -q "## Business Outcomes" "$FILE"; then
    CURRENT_VERSION="2.0.0"
  elif grep -q "##Success Metrics" "$FILE"; then
    CURRENT_VERSION="1.0.0"
  else
    CURRENT_VERSION="unknown"
  fi
fi

echo "Current version: $CURRENT_VERSION"
```

**C) Determine latest template version:**
```bash
# Read from template file
LATEST_VERSION=$(grep "template_version:" "templates/vision.template.md" | sed 's/.*: "//' | sed 's/"$//')
echo "Latest version: $LATEST_VERSION"

if [ "$CURRENT_VERSION" = "$LATEST_VERSION" ]; then
  echo "Document is already at latest version. No upgrade needed."
  exit 0
fi
```

### 2. CREATE BACKUP

**Always create timestamped backup:**
```bash
BACKUP_FILE="${FILE}.backup-$(date +%Y-%m-%d-%H%M%S)"
cp "$FILE" "$BACKUP_FILE"
echo "✅ Backup created: $BACKUP_FILE"
```

### 3. APPLY INCREMENTAL MIGRATIONS

**Use migration system from scripts/utils/template-migrations.ts:**

```typescript
import { applyMigrations, getMigrationPath } from './scripts/utils/template-migrations';

// Get migration path (e.g., 1.0 → 1.1 → 1.2 → 2.0)
const path = getMigrationPath(currentVersion, latestVersion);

console.log(`Migration path: ${path.join(' → ')}`);

// Apply each migration incrementally
let content = readFileSync(filePath, 'utf-8');

for (const migration of path) {
  content = migration.apply(content);
  console.log(`✅ Applied migration ${migration.fromVersion} → ${migration.toVersion}`);
}
```

**Migration Example (vision v1.0 → v2.0):**
```typescript
{
  fromVersion: '1.0.0',
  toVersion: '2.0.0',
  apply: (content) => {
    // Add Business Outcomes section after Vision Statement
    if (!content.includes('## 🎯 Business Outcomes')) {
      content = content.replace(
        /## Vision Statement/,
        `## 🎯 Business Outcomes (Why This Matters)

{{BUSINESS_OUTCOMES_TABLE}}

---

## Vision Statement`
      );
    }
    
    // Add Capability Ladder after Business Outcomes
    if (!content.includes('## 📈 Capability Ladder')) {
      content = content.replace(
        /## Success Metrics/,
        `## 📈 Capability Ladder

{{CAPABILITY_LADDER_TABLE}}

---

## Success Metrics`
      );
    }
    
    // Add Strategic Position section
    if (!content.includes('## 💡 Strategic Position')) {
      content = content.replace(
        /## Integration Summary/,
        `## 💡 Strategic Position

{{STRATEGIC_POSITION}}

---

## Integration Summary`
      );
    }
    
    return content;
  }
}
```

### 4. SHOW WHAT'S NEW

**List new sections added:**
```
✨ New sections added to vision.md:

1. Business Outcomes (line 42)
   - Placeholder: {{BUSINESS_OUTCOMES_TABLE}}
   - TODO: Add your business metrics and outcomes

2. Capability Ladder (line 68)
   - Placeholder: {{CAPABILITY_LADDER_TABLE}}
   - TODO: Define your capability levels (0-6)

3. Strategic Position (line 125)
   - Placeholder: {{STRATEGIC_POSITION}}
   - TODO: Describe market positioning and differentiation

Action required: Fill in {{PLACEHOLDERS}} with your content.
```

### 5. SHOW DIFF

**Display side-by-side diff:**
```bash
# Use diff to show changes
diff --color --unified=3 "$BACKUP_FILE" "$FILE"

# Or for better formatting:
git diff --no-index --color "$BACKUP_FILE" "$FILE"
```

**Example output:**
```diff
--- memory-bank/activeContext.md.backup-2025-10-17
+++ memory-bank/activeContext.md
@@ -39,6 +39,15 @@
 
 **An AI onboarding system that 10X's team productivity...**
 
+## 🎯 Business Outcomes (Why This Matters)
+
+{{BUSINESS_OUTCOMES_TABLE}}
+
+---
+
 ## Success Metrics
 
 | Metric | Target |
```

### 6. CONFIRM SAVE

**Ask before writing:**
```
Preview complete. The document has been upgraded with new sections.

Next steps:
1. Review the diff above
2. Confirm save
3. Edit file to fill in {{PLACEHOLDERS}}

Save changes to memory-bank/activeContext.md? (yes/no)
```

**User must type `yes` to save.**

### 7. UPDATE METADATA

**Update frontmatter:**
```yaml
---
template_version: "2.0.0"
last_updated: "2025-10-17"
migrated_from: "1.0.0"
migration_date: "2025-10-17"
---
```

**Insert at top of file if not present:**
```bash
# Add frontmatter if file doesn't have it
if ! head -1 "$FILE" | grep -q "^---$"; then
  cat > "$FILE.tmp" <<EOF
---
template_version: "$LATEST_VERSION"
last_updated: "$(date +%Y-%m-%d)"
---

$(cat "$FILE")
EOF
  mv "$FILE.tmp" "$FILE"
fi
```

### 8. SUMMARY

**Show completion summary:**
```
✅ Document upgrade complete!

Updated: memory-bank/activeContext.md
- Version: 1.0.0 → 2.0.0
- Backup: memory-bank/activeContext.md.backup-2025-10-17-143022
- New sections: 3
- Placeholders: 3

Next steps:
1. Open memory-bank/activeContext.md
2. Search for {{PLACEHOLDERS}}
3. Replace with your content:
   - {{BUSINESS_OUTCOMES_TABLE}} - Your business metrics
   - {{CAPABILITY_LADDER_TABLE}} - Your capability levels
   - {{STRATEGIC_POSITION}} - Your market positioning
4. Commit changes when ready

To revert (if using legacy path: `context/vision.md`):
```bash
cp memory-bank/activeContext.md.backup-2025-10-17-143022 memory-bank/activeContext.md
```
```

## Document-Specific Migrations

### vision.md → memory-bank/activeContext.md

**v1.0 → v2.0 changes:**
- Add Business Outcomes section
- Add Capability Ladder section
- Add Strategic Position section
- Rename "Success Criteria" to "Business/Product Success"
- Add "Document Purpose" note (PRD vs Spec)

### spec.md (context/specs/*.md)

**v1.0 → v2.0 changes:**
- Rename from prd.template.md to spec.template.md
- Focus on technical implementation (HOW)
- Add "Context Note" in Technical Implementation section
- Add "Related Spec" validation in Definition of Done

### current-release.md (memory-bank/releases/current-release.md)

**v1.0 → v1.1 changes:**
- Add dependency tracking for epics
- Add risk level indicators
- Add effort estimates
- Improve epic structure formatting

## Supported Migrations

**Current migration paths:**
```
vision:
- 1.0.0 → 2.0.0 (add Business Outcomes, Capability Ladder, Strategic Position)

spec:
- 1.0.0 → 2.0.0 (rename from prd, focus on technical implementation)

current-release:
- 1.0.0 → 1.1.0 (add dependencies, risk, effort)

future-releases:
- 1.0.0 → 1.1.0 (add phase planning, epic grouping)

minor-release:
- 1.0.0 → 1.1.0 (add quick wins, impact assessment)
```

## Error Handling

**If migration fails:**
```
❌ Migration failed: [error message]

Your original file is safe:
- Backup: memory-bank/activeContext.md.backup-2025-10-17-143022
- Original: memory-bank/activeContext.md (unchanged)

No changes were saved. Please report this error.
```

**If backup file already exists:**
```
⚠️ Backup file already exists: memory-bank/activeContext.md.backup-2025-10-17

Options:
1. Use different timestamp (recommended)
2. Overwrite existing backup
3. Cancel operation

Choose: [1]
```

## Best Practices

**1. Run after upstream sync:**
```bash
# After pulling platform updates
git pull upstream main
/update-my-documents all
```

**2. Review diffs carefully:**
- Ensure no content lost
- Check placeholder placement
- Verify section order

**3. Fill placeholders incrementally:**
- Start with critical sections
- Use existing content as reference
- Commit after each section complete

**4. Keep backups:**
- Don't delete .backup files immediately
- Keep until changes verified
- Helps rollback if needed

## Integration with update-roadcrew

**Automatic prompt after upstream sync:**
```bash
# In update-roadcrew.sh
echo "Upstream changes pulled successfully."
echo ""
echo "Template versions updated. Would you like to upgrade your documents?"
echo "Run: /update-my-documents all"
```