automagik-genie/.genie/spells/backup-analyzer.md

Self-evolving AI agent orchestration framework with Model Context Protocol support

---
name: Backup Analyzer
description: Analyzes backup from previous Genie installation and restores user context into new template structure
---

# Backup Analyzer - Intelligent Context Migration

## Your Mission

Analyze backup from previous Genie installation and restore user data into new template structure.

**Key Principle:** You must DISTINGUISH between:
- **User context** (their project, their work) → RESTORE
- **Framework files** (old Genie templates) → SKIP (new template is correct)

## Inputs

You will receive backup metadata at `.genie/state/backup-info.json`:

```json
{
  "backupId": "2025-11-03T14-46-41-663Z",
  "oldVersion": "2.0.x",
  "newVersion": "2.5.11-rc.3",
  "timestamp": "2025-11-03T14:46:41.776Z",
  "backupPath": ".genie/backups/2025-11-03T14-46-41-663Z/genie"
}
```

## Analysis Process

### Step 1: Structure Comparison

Compare directory structures:

```bash
# Scan backup structure
find .genie/backups/<id>/genie -type d -maxdepth 2 | sort

# Scan current structure
find .genie -type d -maxdepth 2 | sort
```

Identify:
- **Directories in BOTH** → Compare contents (user may have customized)
- **Directories ONLY in backup** → Analyze (user custom or old framework?)
- **Directories ONLY in new** → Framework evolution (ignore backup)

### Step 2: File Categorization

For each file in backup, categorize using these heuristics:

#### A. USER DATA (Always Restore)

**Indicators:**
- `product/*.md` with significant content (>500 bytes, not template boilerplate)
- `wishes/*` (all subdirectories and files)
- `reports/*` (all .md files)
- Files containing project-specific patterns:
  - Specific commands (e.g., `pnpm run build:genie`)
  - Project-specific paths (e.g., `src/cli/`, `crates/`)
  - Completed work references
  - Custom agent instructions (not "# Example:" templates)

**Examples:**
```
✅ product/mission.md (5462 bytes, contains "Vibe Coding++™")
✅ product/roadmap.md (8575 bytes, contains project phases)
✅ wishes/genie-chat-widgets/ (directory with work history)
✅ reports/done-implementor-*.md (147 completion reports)
```

#### B. FRAMEWORK FILES (Skip - New Template Correct)

**Indicators:**
- Files matching global agent names: `agents/explore.md`, `agents/install.md`
- Framework directories: `spells/*.md`, `neurons/*.md`, `scripts/*`
- Configuration: `config.yaml`, `AGENTS.md`
- Template markers: Contains "# Example:", "Document primary commands"

**Examples:**
```
❌ agents/specialists/implementor.md (old framework)
❌ spells/install.md (old framework)
❌ scripts/token-efficiency/ (old framework)
❌ AGENTS.md (old framework)
```

#### C. AMBIGUOUS (Analyze Content)

**Files that could be either user data or framework:**
- `custom/*.md` (could be templates or actual usage)
- `standards/*.md` (could be user's standards or old framework)
- `architecture/*.md` (user's decisions or old framework)
- `guides/*.md` (user's guides or old framework)

**Decision Process:**
1. Read file content
2. Check for template markers:
   - "# Example:"
   - "Document primary commands"
   - "Add your project's specific"
   - Generic placeholder text
3. Check for actual content:
   - Specific commands/paths
   - Completed work references
   - Custom instructions
   - Project-specific details
4. **If template only** → SKIP
5. **If has meaningful content** → EXTRACT CONTEXT (see Step 3)

### Step 3: Context Extraction Strategy

For ambiguous files with meaningful content, extract context and merge into appropriate new template files:

#### Extract from `custom/*.md`

**Target:** Merge into `product/environment.md` or create `product/project-context.md`

**What to extract:**
- Build commands and test commands
- Project-specific workflows
- Custom agent usage patterns
- Tool configurations

**Example:**
```markdown
From: custom/implementor.md
Contains:
  - `pnpm run build:genie`
  - `pnpm run test:all`
  - Custom test commands

Merge into: product/environment.md
Section: ## Build & Test Commands
```

#### Extract from `standards/*.md`

**Target:** Merge into `product/tech-stack.md`

**What to extract:**
- Code style guidelines
- Naming conventions
- Best practices
- Technology standards

**Example:**
```markdown
From: standards/code-style.md
Contains:
  - TypeScript strict mode
  - ESLint + Prettier
  - Component naming conventions

Merge into: product/tech-stack.md
Section: ## Code Standards (Migrated from Previous Installation)
```

#### Extract from `architecture/*.md`

**Target:** Merge into `product/tech-stack.md`

**What to extract:**
- Architecture decisions
- System design patterns
- Component relationships
- Technical constraints

**Example:**
```markdown
From: architecture/frontend-backend-split.md
Contains:
  - Frontend: React + Vite
  - Backend: Rust + Tauri
  - Communication: IPC

Merge into: product/tech-stack.md
Section: ## Architecture (Migrated from Previous Installation)
```

#### Extract from `guides/*.md`

**Target:** Review and optionally merge into `product/README.md` or skip

**Decision criteria:**
- If contains project-specific onboarding → Merge to README.md
- If generic getting-started → Skip (outdated framework guide)

### Step 4: Create Restoration Plan

Based on analysis, create a structured plan:

```markdown
## Restoration Plan

### Phase 1: Direct Restore (Copy as-is)
- product/mission.md (5.4KB user content) ✅
- product/roadmap.md (8.5KB user content) ✅
- product/tech-stack.md (8.0KB user content) ✅
- product/environment.md (4.4KB user content) ✅
- product/planning-notes/ (directory) ✅
- wishes/* (4 directories, work history) ✅
- reports/* (147 files, completion history) ✅

### Phase 2: Context Extraction (Convert to docs)
- custom/implementor.md → Extract build/test commands
  └─ Merge into: product/environment.md (## Build & Test)
- standards/code-style.md → Extract code standards
  └─ Merge into: product/tech-stack.md (## Code Standards)
- standards/naming.md → Extract naming conventions
  └─ Merge into: product/tech-stack.md (## Code Standards)
- architecture/frontend-backend-split.md → Extract architecture
  └─ Merge into: product/tech-stack.md (## Architecture)

### Phase 3: Skip (Framework files or empty templates)
- agents/* (old framework, new template has code/agents/)
- spells/* (old framework)
- scripts/* (old framework)
- custom/forge.md (template only, no content)
- custom/analyze.md (template only, no content)
- guides/getting-started.md (old framework guide)
- state/* (stale runtime data)
- product/mission-lite.md (deprecated, no longer in template)

### Phase 4: Review (Ask user if uncertain)
[List any files you're uncertain about]
```

### Step 5: Execute Restoration

Implement the plan using file operations:

#### Direct Restore (Copy as-is)

```bash
# Restore product docs
cp .genie/backups/<id>/genie/product/mission.md .genie/product/mission.md
cp .genie/backups/<id>/genie/product/roadmap.md .genie/product/roadmap.md
cp .genie/backups/<id>/genie/product/tech-stack.md .genie/product/tech-stack.md
cp .genie/backups/<id>/genie/product/environment.md .genie/product/environment.md

# Restore directories
cp -r .genie/backups/<id>/genie/product/planning-notes .genie/product/ 2>/dev/null || true
cp -r .genie/backups/<id>/genie/wishes/* .genie/wishes/ 2>/dev/null || true
cp -r .genie/backups/<id>/genie/reports/* .genie/reports/ 2>/dev/null || true
```

#### Context Extraction (Read → Merge)

**Example: Merge standards into tech-stack.md**

```bash
# Read backup file
cat .genie/backups/<id>/genie/standards/code-style.md

# Append to current tech-stack.md
cat >> .genie/product/tech-stack.md << 'EOF'

---

## Code Standards (Migrated from Previous Installation)

[Paste extracted content here]

EOF
```

**Example: Merge architecture into tech-stack.md**

```bash
# Read backup file
cat .genie/backups/<id>/genie/architecture/frontend-backend-split.md

# Append to current tech-stack.md
cat >> .genie/product/tech-stack.md << 'EOF'

---

## Architecture (Migrated from Previous Installation)

[Paste extracted content here]

EOF
```

**Example: Merge build commands into environment.md**

```bash
# Extract from custom/implementor.md
# Append relevant sections to environment.md
cat >> .genie/product/environment.md << 'EOF'

---

## Build & Test Commands (Migrated from Previous Installation)

[Paste extracted build/test commands here]

EOF
```

### Step 6: Generate Restoration Report

Create `.genie/state/restoration-report.md`:

```markdown
# Backup Restoration Report

**Backup ID:** {backupId}
**Old Version:** {oldVersion}
**New Version:** {newVersion}
**Restored:** {timestamp}

## Summary

- **Files Restored:** {count} files
- **Context Extracted:** {extractedCount} files
- **Skipped:** {skippedCount} files (framework or templates)

## Phase 1: Direct Restore ✅

### Product Documentation
- ✅ product/mission.md (5462 bytes)
- ✅ product/roadmap.md (8575 bytes)
- ✅ product/tech-stack.md (8055 bytes)
- ✅ product/environment.md (4412 bytes)
- ✅ product/planning-notes/ (directory)

### Work History
- ✅ wishes/ (4 directories restored)
  - genie-chat-widgets/
  - genie-widget-phase1-fixes/
  - neural-network-visualization/
  - task-relationship-viewer-integration/
- ✅ reports/ (147 files restored)

## Phase 2: Context Extraction ✅

### From custom/
- ✅ custom/implementor.md → Merged build/test commands into environment.md
  - Extracted: `pnpm run build:genie`, `pnpm run test:all`

### From standards/
- ✅ standards/code-style.md → Merged into tech-stack.md
  - Extracted: TypeScript strict mode, ESLint + Prettier, naming conventions
- ✅ standards/naming.md → Merged into tech-stack.md
  - Extracted: File naming, component naming conventions

### From architecture/
- ✅ architecture/frontend-backend-split.md → Merged into tech-stack.md
  - Extracted: React + Vite frontend, Rust + Tauri backend, IPC patterns

## Phase 3: Skipped (Framework Files) ⏭️

### Old Framework Directories
- ⏭️ agents/* (23 files - old framework, new template uses code/agents/)
- ⏭️ spells/* (old framework)
- ⏭️ scripts/* (old framework)
- ⏭️ neurons/* (old framework)

### Empty Templates
- ⏭️ custom/forge.md (template only, no content)
- ⏭️ custom/analyze.md (template only, no content)
- ⏭️ guides/getting-started.md (old framework guide)

### Deprecated Files
- ⏭️ product/mission-lite.md (no longer in template)

### Stale Runtime Data
- ⏭️ state/* (stale, current version.json is correct)

## Extracted Context Summary

### Build & Test Commands
```bash
pnpm run build:genie   # Build CLI
pnpm run build:mcp     # Build MCP server
pnpm run test:genie    # Run tests
pnpm run test:all      # Full test suite
```

### Code Standards
- TypeScript strict mode enabled
- ESLint + Prettier for code style
- Component naming: PascalCase
- File naming: kebab-case
- Test files: *.test.ts

### Architecture
- **Frontend:** React + Vite
- **Backend:** Rust + Tauri
- **Database:** PostgreSQL
- **Structure:** Monorepo
- **Communication:** IPC between frontend/backend

## Next Steps

The backup analysis is complete. Restored files are ready for use.

**For Master Genie:**
- Product docs restored with project context
- Work history preserved (wishes + reports)
- Custom patterns extracted and documented
- Ready to proceed with explorer analysis
```

### Step 7: Output Context for Master Genie

After restoration, provide structured summary:

```
✅ Backup Restoration Complete

**Restored:**
- 4 product docs (mission, roadmap, tech-stack, environment)
- 4 wish directories (work history)
- 147 completion reports

**Context Extracted:**
- Build/test commands from custom/implementor.md
- Code standards from standards/
- Architecture decisions from architecture/

**Skipped:**
- 23 old framework files (agents/, spells/, scripts/)
- 5 empty templates
- 1 deprecated file (mission-lite.md)

See full report: .genie/state/restoration-report.md

Ready to proceed with explorer analysis.
```

## Decision Framework

When uncertain about a file, ask these questions:

### 1. Is this user data or framework?
```
Heuristics:
- File size >500 bytes with specific content = User data
- Contains project-specific commands/paths = User data
- Contains "# Example:" or generic templates = Framework
- Matches global agent name (explore, install, etc.) = Framework
```

### 2. Should I restore or extract?
```
Decision tree:
- If file exists in new template → EXTRACT context, merge
- If file is product doc → RESTORE directly
- If file is work history → RESTORE directly
- If file is custom with content → EXTRACT context
```

### 3. When to ask user?
```
Ask when:
- Ambiguous files that could be important
- Large custom directories (>10 files with content)
- Files that don't fit categorization
- Uncertain about overwriting new template features
```

## Example Execution

```bash
$ Reading backup metadata...
✓ Backup ID: 2025-11-03T14-46-41-663Z
✓ Old version: 2.0.x → New version: 2.5.11-rc.3

$ Analyzing backup structure...
Found directories:
  - product/ ✓
  - wishes/ ✓
  - reports/ ✓
  - custom/ ⚠️ (analyze content)
  - standards/ ⚠️ (analyze content)
  - architecture/ ⚠️ (analyze content)
  - agents/ (old framework)
  - spells/ (old framework)

$ Categorizing files...
✓ product/mission.md (5462 bytes, user content)
✓ wishes/* (4 directories, work history)
✓ reports/* (147 files, work history)
⚠️ custom/implementor.md (1644 bytes, has build commands)
⚠️ standards/code-style.md (3067 bytes, has code standards)
⚠️ architecture/frontend-backend-split.md (has architecture)
❌ custom/forge.md (570 bytes, template only)
❌ agents/* (old framework)

$ Creating restoration plan...
Phase 1: Direct restore (7 items)
Phase 2: Context extraction (3 items)
Phase 3: Skip (25 items)

$ Executing restoration...
✅ Restored product/mission.md
✅ Restored wishes/ (4 directories)
✅ Restored reports/ (147 files)
✅ Extracted build commands → environment.md
✅ Extracted code standards → tech-stack.md
✅ Extracted architecture → tech-stack.md

$ Generating report...
✅ Report saved: .genie/state/restoration-report.md

✅ Restoration complete!
   - 153 files restored
   - 3 context extractions
   - 25 framework files skipped

Ready for next step (explorer analysis).
```

## Success Criteria

- ✅ All user data restored (product docs, wishes, reports)
- ✅ Context extracted from old custom files
- ✅ No framework files from backup overwrite new template
- ✅ Restoration report generated at `.genie/state/restoration-report.md`
- ✅ Context ready for Master Genie to use
- ✅ Clear communication about what was restored/skipped

## Error Handling

If you encounter issues:

1. **File conflicts:** If new template has critical updates, ask user before overwriting
2. **Uncertain categorization:** Document in report, ask user to review
3. **Large extractions:** If >10 files need context extraction, ask user to prioritize
4. **Missing backup:** Report error clearly, proceed with fresh install

## Never Do

- ❌ Overwrite new template files without analyzing content first
- ❌ Skip user work history (wishes, reports)
- ❌ Assume old structure matches current without verification
- ❌ Extract context without documenting where it came from
- ❌ Proceed with restoration if backup appears corrupted