/migration-preflight - Migration Pre-flight Checklist

Execute a comprehensive safety checklist before any migration operation. Created after the ADR-100 disaster that corrupted 100+ files.

Usage

# Interactive checklist
/migration-preflight

# For specific migration
/migration-preflight --migration nomenclature

# Skip interactive, just validate
/migration-preflight --validate-only

# Mark pre-flight complete (creates marker file)
/migration-preflight --complete

System Prompt

EXECUTION DIRECTIVE: When the user invokes /migration-preflight, you MUST:

1. Display the pre-flight checklist interactively
2. Validate each item by running actual checks
3. Block if critical items fail
4. Create marker file when all checks pass

CRITICAL: This command was created after the ADR-100 nomenclature migration disaster that corrupted 100+ Python files. NEVER skip this checklist for migration operations.

Pre-flight Checklist

Phase 1: Preparation (Required)

#	Check	Command	Required
1.1	Git status clean	git status --porcelain	Yes
1.2	On correct branch	git branch --show-current	Yes
1.3	Remote up to date	git fetch && git status -sb	Yes
1.4	Backup created	ls ~/coditect-recovery-backup/	Yes
1.5	Migration script exists	ls scripts/migrations/	Yes

Phase 2: Validation (Required)

#	Check	Command	Required
2.1	Dry-run available	python3 script.py --help | grep dry-run	Yes
2.2	Dry-run succeeds	python3 script.py --dry-run	Yes
2.3	No syntax errors	find . -name "*.py" -exec python3 -m py_compile {} \;	Yes
2.4	Context-aware replacement	Check for is_valid_path_context()	Yes

Phase 3: Safety (Required)

#	Check	Command	Required
3.1	Rollback plan documented	Check MIGRATION-PLAN.md	Yes
3.2	Affected files listed	Dry-run output reviewed	Yes
3.3	No protected names in str.replace	Grep for dangerous patterns	Yes
3.4	Symlinks planned	Check for backward compatibility	Yes

Phase 4: Approval (Required)

#	Check	Command	Required
4.1	Human approval	Interactive confirmation	Yes
4.2	Marker file created	touch ~/.coditect/.migration-preflight-complete	Yes

Execution Script

#!/bin/bash
# migration-preflight.sh

echo "=============================================="
echo "MIGRATION PRE-FLIGHT CHECKLIST"
echo "=============================================="
echo ""

FAILED=0

# Phase 1: Preparation
echo "Phase 1: Preparation"
echo "--------------------"

# 1.1 Git status clean
if [ -z "$(git status --porcelain)" ]; then
    echo "  [✓] 1.1 Git status clean"
else
    echo "  [✗] 1.1 Git status NOT clean - commit or stash changes first"
    FAILED=1
fi

# 1.2 Backup exists
if [ -d ~/coditect-recovery-backup ]; then
    echo "  [✓] 1.2 Backup directory exists"
else
    echo "  [✗] 1.2 No backup directory - run: mkdir -p ~/coditect-recovery-backup"
    FAILED=1
fi

# 1.3 Current commit logged
CURRENT_COMMIT=$(git rev-parse HEAD)
echo "  [i] 1.3 Current commit: $CURRENT_COMMIT"

# Phase 2: Validation
echo ""
echo "Phase 2: Validation"
echo "-------------------"

# 2.1 Check for dangerous patterns
DANGEROUS=$(grep -r "str\.replace.*hooks\|str\.replace.*config\|str\.replace.*scripts" scripts/migrations/*.py 2>/dev/null | grep -v "context_aware")
if [ -z "$DANGEROUS" ]; then
    echo "  [✓] 2.1 No dangerous str.replace() patterns"
else
    echo "  [✗] 2.1 DANGEROUS: Found naive str.replace() on protected names"
    echo "$DANGEROUS"
    FAILED=1
fi

# 2.2 Python syntax check
echo "  [i] 2.2 Validating Python syntax..."
SYNTAX_ERRORS=$(find . -name "*.py" -exec python3 -m py_compile {} \; 2>&1)
if [ -z "$SYNTAX_ERRORS" ]; then
    echo "  [✓] 2.2 All Python files valid"
else
    echo "  [✗] 2.2 Python syntax errors found:"
    echo "$SYNTAX_ERRORS"
    FAILED=1
fi

# Phase 3: Final Checks
echo ""
echo "Phase 3: Final Checks"
echo "---------------------"

if [ $FAILED -eq 0 ]; then
    echo "  [✓] All checks passed!"
    echo ""
    echo "Creating pre-flight marker..."
    touch ~/.coditect/.migration-preflight-complete
    echo "  [✓] Marker created: ~/.coditect/.migration-preflight-complete"
    echo ""
    echo "You may now proceed with migration using --dry-run first!"
else
    echo ""
    echo "  [✗] PRE-FLIGHT FAILED - Fix issues above before proceeding"
    exit 1
fi

Example Output

==============================================
MIGRATION PRE-FLIGHT CHECKLIST
==============================================

Phase 1: Preparation
--------------------
  [✓] 1.1 Git status clean
  [✓] 1.2 Backup directory exists
  [i] 1.3 Current commit: 0326f1d8

Phase 2: Validation
-------------------
  [✓] 2.1 No dangerous str.replace() patterns
  [i] 2.2 Validating Python syntax...
  [✓] 2.2 All Python files valid

Phase 3: Final Checks
---------------------
  [✓] All checks passed!

Creating pre-flight marker...
  [✓] Marker created: ~/.coditect/.migration-preflight-complete

You may now proceed with migration using --dry-run first!

Dangerous Patterns Detected

The following patterns will FAIL the pre-flight check:

# DANGEROUS - Will be blocked
content.replace("hooks", "new_name")
str.replace("config", "H.P.009-CONFIG")
text.replace("scripts", replacement)

# SAFE - Uses context-aware replacement
context_aware_replace(content, "hooks", "new_name")
if is_valid_path_context(content, pos, "hooks"):
    content = content[:pos] + new_name + content[pos+len("hooks"):]

Related

• ADR-100: Unified Nomenclature Standard
• Incident Retrospective
• migration-safety-validator.py
• /risk-assess

Success Output

✅ COMMAND COMPLETE: /migration-preflight
All 12 checks passed
Marker created: ~/.coditect/.migration-preflight-complete
Safe to proceed with migration (use --dry-run first)

Failure Output

❌ PRE-FLIGHT FAILED: 3 checks failed

Failed checks:
- 1.1 Git status not clean
- 2.1 Dangerous str.replace() pattern detected
- 3.1 No rollback plan documented

Fix these issues before proceeding with migration.

---

Created: 2026-01-22 (Post ADR-100 Disaster) Author: CODITECT Core Team