# Legacy First Real Run Checklist

Date: 2026-05-25

## Purpose

This checklist is the **first real execution checklist** after running:

```bash
php artisan legacy:import
```

Use it for the first production or staging run against the real legacy database.

## Step 1: Record the Run ID

Immediately after the command finishes, note:

- run reference
- run id
- legacy connection name used
- counts shown for:
  - legacy formations
  - legacy sessions
  - legacy students
- sample formation names printed by the command

If the command does not show these, stop and do not continue blindly.

## Step 2: Open the Run Screens

Open these pages in order:

1. `/admin/legacy-imports`
2. `/admin/legacy-imports/RUN_ID`
3. `/admin/legacy-imports/course-mapping?run=RUN_ID`
4. `/admin/legacy-imports/session-mapping?run=RUN_ID`
5. `/admin/legacy-imports/review?run=RUN_ID&focusMode=historical_completed`

## Step 3: Confirm the Import Is Not Empty

On the run detail page, confirm:

- the run exists
- `students_count > 0`
- `references_count > 0`
- dry-run summary is visible

If any of these is missing:

- stop
- review connection and source table names

## Step 4: Check Course Names

Open:

- `/admin/legacy-imports/course-mapping?run=RUN_ID`

Verify:

1. legacy formation names are visible
2. they are not all `Unknown formation`
3. the names roughly match what exists in the old platform
4. the count is believable compared to the old `formations` table

If many rows show `Unknown formation`:

- stop
- inspect the legacy `formations` column names
- do not continue to commit

## Step 5: Check Session Quality

Open:

- `/admin/legacy-imports/session-mapping?run=RUN_ID`

Verify:

1. placeholder sessions `1 / 2 / 235` are not treated as real sessions
2. waiting sessions remain `placeholder_session` or `waiting_session`
3. real sessions have believable codes and linked formation ids

If waiting sessions look like real sessions:

- stop
- fix the classification before continuing

## Step 6: Check Historical Completed First

Open:

- `/admin/legacy-imports/review?run=RUN_ID&focusMode=historical_completed`

Review at least:

1. 20 records classified `completed`
2. 20 records classified `archived_training`
3. 10 records with duplicate hints

Confirm:

- student names look correct
- phone normalization looks sane
- emails are masked in lists
- classifications match reality
- historical training rows are not being treated as simple leads

## Step 7: Check Duplicates

On the review pages, inspect:

- `duplicate_confidence = high`
- `duplicate_confidence = medium`

Confirm:

- high-confidence duplicates make sense
- there is no obvious false-positive pattern

If duplicate matching looks suspicious:

- stop
- do not commit

## Step 8: Run Validate / Classify / Dry Run

Run:

```bash
php artisan legacy:validate --run=RUN_ID
php artisan legacy:classify --run=RUN_ID
php artisan legacy:dry-run --run=RUN_ID
```

Then return to:

- `/admin/legacy-imports/RUN_ID`

Check:

1. completed history totals
2. archived training totals
3. registered pending totals
4. lead-only totals
5. duplicate totals
6. placeholder session totals
7. unmapped course totals

## Step 9: Decide Go / No-Go

You may proceed only if:

- course names are visible and believable
- placeholder sessions are correctly isolated
- completed-history sampling looks correct
- duplicate hints look trustworthy
- dry-run totals look reasonable

Do **not** proceed if:

- many formations are unknown
- many rows are misclassified
- placeholders look real
- duplicates look unsafe

## Step 10: Export Before Commit

From the run detail page, export:

- masked CSV
- JSON summary

Save them as the review artifacts for this run.

## Step 11: First Commit Batch

For the first real execution:

- commit only a very small batch
- prefer historical completed rows first

Recommended first command:

```bash
php artisan legacy:commit --run=RUN_ID --batch=25
```

Then verify the result before any second batch.

## Step 12: Post-Commit Spot Check

After the first batch:

1. reopen `/admin/legacy-imports/RUN_ID`
2. review commit summary
3. check commit history
4. confirm no unexpected modern business writes happened
5. confirm historical rows landed only in safe compatibility targets

## Step 13: Rollback Drill

Before scaling up, run one rollback drill:

```bash
php artisan legacy:rollback --run=RUN_ID
```

Confirm:

- safe-created records are removed or reset
- pre-existing users remain untouched
- rollback logs exist

If rollback is not clean, stop immediately.

## Final Rule

The first real run is successful only if:

- import succeeded
- mapping visibility is correct
- dry-run looks believable
- first batch commit is clean
- rollback drill is clean

If one of these fails, treat the run as **not approved**.