---
name: lc:migration-fresh-test
description: Run migrate:fresh in Docker and report errors with fix suggestions.
argument-hint: "[analyze | fix | fix --dry-run | --seed]"
user-invocable: true
allowed-tools: Read Grep Bash Edit Write Glob
---

# Migration Fresh Test

Run `php artisan migrate:fresh` inside the project's Docker container and provide detailed error analysis with fix suggestions when migrations fail.

## Subcommands

| Subcommand | Description |
|---|---|
| *(no argument)* | Run migrate:fresh, report any errors with root cause analysis. |
| `fix` | Run migrate:fresh and auto-fix each error encountered, with confirmation before each fix. Re-runs after each fix until all migrations pass. |
| `fix --dry-run` | Run migrate:fresh, diagnose errors, show what fixes would be applied without changing anything. |
| `--seed` | Run migrate:fresh --seed (can be combined with fix modes). |

## Process

### Step 1: Detect Docker Container

1. Use `Read` to examine `docker-compose.yml` in the project root.
2. Identify the PHP/application service (typically named `app`, `laravel`, or similar -- look for the service that mounts the application code and runs PHP).
3. Determine the container name. Convention is usually `{project}_app` or defined via `container_name` in docker-compose.yml.
4. Verify the container is running with `docker ps --filter name={container_name} --format '{{.Names}}'` via `Bash`.
5. If the container is not running, inform the user and suggest `docker compose up -d`.

### Step 2: Pre-flight Checks

1. **Check for schema dump files**: Use `Glob` to look for `database/schema/*.sql`. If found, warn the user that schema dumps can cause migrations to be skipped (old migrations won't run, data imports may be lost). Ask if they want to remove the schema dump first.
2. **Syntax check all migrations**: Run `php -l` on each migration file to catch parse errors before running the full migration. Use `Bash`:
   ```
   docker exec {container} find /var/www/html/database/migrations -name "*.php" -exec php -l {} \;
   ```
   If any syntax errors are found, report them immediately with file path and line number. Read the file to show the problematic code and suggest a fix. Stop here until syntax errors are resolved.

### Step 3: Run migrate:fresh

1. Build the command:
   - Base: `docker exec {container} php artisan migrate:fresh`
   - If `--seed` argument was provided, append `--seed`
   - Always add `--force` to bypass production checks
   - Add `2>&1` to capture both stdout and stderr
2. Run via `Bash` with a generous timeout (migrations with data imports can take minutes).
3. Capture the full output.

### Step 4: Analyze Results

#### If successful:
Report success with:
- Total migrations run
- Time taken
- If `--seed` was used, seeder results
- Any warnings in the output (deprecation notices, etc.)

#### If failed:
Parse the error output to identify:

1. **The failing migration**: Extract the migration filename from the error output (typically shown as "Migrating: {filename}").
2. **The SQL error**: Extract the actual SQL error message.
3. **The error type**: Classify into one of the known patterns below.

### Step 5: Diagnose and Suggest Fixes

For each error, use `Read` to examine the failing migration and related files, then provide a diagnosis:

#### Common Error Patterns

**Foreign Key Constraint Failure**
- Pattern: `Cannot add foreign key constraint` or `SQLSTATE[HY000]: General error: 1215`
- Cause: Referenced table doesn't exist yet (migration order issue) or column types don't match
- Diagnosis: Read the migration, find the FK definition, check if the referenced table's migration has an earlier timestamp
- Fix: Suggest renaming the migration file to adjust timestamp order, or splitting the FK into a separate later migration

**Table Already Exists**
- Pattern: `Table '{table}' already exists` or `SQLSTATE[42S01]`
- Cause: Duplicate CREATE migration, or schema dump + migration both create the same table
- Diagnosis: Search for all migrations that create this table
- Fix: Remove duplicate migration or schema dump

**Column Already Exists**
- Pattern: `Duplicate column name '{column}'` or `SQLSTATE[42S21]`
- Cause: Column added in CREATE migration and again in ALTER migration
- Diagnosis: Find all migrations that add this column
- Fix: Remove the duplicate column addition

**Unknown Column**
- Pattern: `Unknown column '{column}'` or `SQLSTATE[42S22]`
- Cause: Migration references a column that hasn't been created yet, or was dropped
- Diagnosis: Trace the column through all migrations
- Fix: Adjust migration order or fix column name

**Data Type Mismatch**
- Pattern: `SQLSTATE[HY000]: General error: 3780` (referencing column type mismatch)
- Cause: FK column type doesn't match the referenced column (e.g., unsigned vs signed, bigint vs int)
- Diagnosis: Compare column definitions in both tables
- Fix: Ensure both columns use the same type (typically `unsignedBigInteger` or `foreignId`)

**SQL Import Error**
- Pattern: Errors during `DB::unprepared()` with large SQL files
- Cause: SQL syntax issues, character encoding, or memory limits
- Diagnosis: Check the SQL file being imported
- Fix: Suggest splitting the import or increasing PHP memory limit

**Class Not Found**
- Pattern: `Class '{class}' not found`
- Cause: Migration references a model or class that was moved/renamed
- Diagnosis: Search for the class in the codebase
- Fix: Update the import/reference

### Step 6: Apply Fixes (fix mode)

In **fix mode**, after diagnosing each error:

1. Show the error clearly with the migration file path and line number.
2. Explain the root cause.
3. Show the specific code that needs to change.
4. **Ask for confirmation** before applying.
5. If confirmed, use `Edit` to apply the fix.
6. **Re-run `migrate:fresh`** to verify the fix and catch the next error.
7. Repeat until all migrations pass or the user decides to stop.

In **fix --dry-run mode**, show all the same information but skip steps 4-7.

In **default mode** (no fix), show the diagnosis and suggested fix but do not apply.

## Output Format

```
PRE-FLIGHT CHECKS
==================
Schema dump: Not found (OK)
Syntax check: 85 migrations checked, 0 errors

MIGRATION RESULTS
==================
Status: FAILED
Failed at: 2025_05_14_214422_create_clients_table.php
Migrations completed before failure: 23/85

ERROR ANALYSIS
===============
Error: Cannot add foreign key constraint
SQL: ALTER TABLE `clients` ADD CONSTRAINT `clients_file_id_foreign` FOREIGN KEY (`file_id`) REFERENCES `files` (`id`)

Root Cause: The `files` table migration (2025_06_01_...) runs AFTER the `clients` table migration (2025_05_14_...).

SUGGESTED FIX
===============
Rename the files migration to run before clients:
  From: 2025_06_01_000000_create_files_table.php
  To:   2025_05_13_000000_create_files_table.php

Apply this fix? [Waiting for confirmation]
```

## Important Notes

- This skill WILL drop all tables and recreate them. It should only be used in development/testing environments.
- Always warn the user that this will destroy all data in the database before proceeding.
- If the project uses SQLite for testing, offer to test against SQLite first as a faster alternative.