Migrate Page

---
description: Turn one of your old HTML pages into a real app page, safely.
argument-hint: '[page or file]'
---

Follow the SHARED WORKFLOW CONTRACT throughout this command:
1. Read docs/STATUS.md, then every file in docs/decisions/ and docs/assumptions/.
2. TDD always — failing test first (RED), confirm it fails, then minimal real code (GREEN), then refactor.
3. Wire real data (real database, real routes) for the slice in hand — do not mock the boundary being built.
4. When something is unspecified, make a reasonable KISS assumption, log it in docs/assumptions/, and continue — never stall.
5. A page is not done until /verify-browser passes.
6. End with a plain-language report and the single recommended next command.
7. Loop to the next un-migrated page and repeat until every page listed in docs/STATUS.md is marked as migrated — that is the stop condition for this command.

---

## Step 1 — Identify the target page

If $ARGUMENTS names a specific page or file, use that. Otherwise, look at docs/STATUS.md and pick the next page that is not yet marked as migrated. Log your choice so the owner can see it.

---

## Step 2 — Capture current behaviour as tests (RED)

Before touching any application code, write tests that describe exactly what the current HTML page shows and does:

- What content appears on the page (headings, labels, lists, buttons).
- What actions a user can take (clicking, submitting forms, navigating).
- What data is displayed and where it comes from (even if it is currently hardcoded in the HTML).

Run the tests. Confirm every one of them FAILS — this is the RED state. Do not proceed until you have confirmed the failures. If a test passes before you have written any new code, that test is wrong — fix it.

---

## Step 3 — Build the real Next.js route (GREEN)

Create the equivalent Next.js App Router route and component:

- Wire it to the real database through the ORM (Prisma or Drizzle as decided). No fake data, no in-memory stubs for the boundary being built.
- Match all the content and behaviour captured in Step 2.
- Keep it simple — do the smallest thing that makes the tests pass.

Run the tests again. Every test from Step 2 must now pass.

---

## Step 4 — Refactor

With tests green, clean up the code:

- Remove duplication.
- Rename anything unclear.
- Make sure the file stays within 800 lines and functions stay under 50 lines.

Run the tests once more to confirm nothing broke.

---

## Step 5 — Verify parity with /verify-browser (done-gate)

Run /verify-browser, comparing the old HTML page against the new Next.js route side by side using the browser-automation MCP. Check:

- The same content is visible.
- The same user actions work the same way.
- No obvious visual regressions.

If parity does not pass, fix the gap and re-run /verify-browser. Do not mark the page as done until parity passes.

---

## Step 6 — Keep the app runnable throughout

- Leave the original .html file completely untouched until parity is confirmed.
- The new route must be reachable and working before the old file is marked replaceable.
- Once parity passes, add a note in docs/STATUS.md marking the old .html file as replaceable (do not delete it — the owner decides when to remove it).

---

## Step 7 — Assume and log

Any time you hit something unspecified — a field whose meaning is unclear, a behaviour that is ambiguous, a data relationship not covered by decisions — make a plain KISS assumption, write it to a new file in docs/assumptions/NNN-<topic>.md, and continue. Each assumption file must open with a plain-English summary of what you assumed and the line: "Tell me if this is wrong."

---

## Step 8 — Update docs/STATUS.md

Update docs/STATUS.md to reflect:

- Which page was just migrated.
- Which pages remain.
- The current state of the app (runnable, tests passing, any known gaps).

Then **commit the migrated page to git** with a clear message (or offer to do it for the owner). Commit after every page so progress is never lost.

---

## Loop — repeat until all pages are migrated

Check docs/STATUS.md. If there are still pages not yet marked as migrated, return to Step 1 and begin the next page. Keep looping until every page is marked as migrated — that is the stop condition. Once all pages are done, end with the final end-of-run report below and recommend /tdd-feature if a new capability is needed, or confirm that migration is complete.

---

## End-of-run report

Write a short plain-language report directly in your response — no jargon, no code dumps — covering:

1. Which page was migrated.
2. What it now does (in the owner's domain language, not technical terms).
3. Any assumptions you made (list each one and where the assumption file lives).
4. Whether the old HTML page is now marked replaceable or if there is still a gap.
5. The single recommended next command — usually /migrate-page for the next un-migrated page, or /tdd-feature if a new capability is needed before the next page can be built.