red/.planning/phases/13-ai-field-placement-and-pre-fill/13-04-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
13-ai-field-placement-and-pre-fill	04	execute	4	13-01 13-02 13-03		false	AI-01 AI-02	truths artifacts key_links Agent can click 'AI Auto-place Fields' on a real document and fields appear on the PDF canvas AI-placed text fields are pre-filled with client name and/or property address where available AI-placed fields are editable — agent can move, resize, and delete them after AI placement Coordinate conversion is correct — fields appear at the expected vertical positions (not inverted) Unit test passes: aiCoordsToPagePdfSpace produces correct Y-axis flip for US Letter dimensions path provides contains teressa-copeland-homes/src/lib/pdf/__tests__/ai-coords.test.ts Passing unit tests for coordinate conversion aiCoordsToPagePdfSpace from to via pattern AI Auto-place button /api/documents/[id]/ai-prepare PreparePanel onAiAutoPlace → DocumentPageClient handleAiAutoPlace → fetch POST ai-prepare from to via pattern FieldPlacer DB (signatureFields) loadFields useEffect re-runs when aiPlacementKey increments aiPlacementKey

Verify the complete AI field placement feature end-to-end: unit tests, integration test with a real document, coordinate accuracy check, and final human UAT sign-off.

Purpose: AI coordinate accuracy on real Utah forms is listed as an explicit concern in STATE.md Blockers/Concerns. This plan is the mandatory verification gate before Phase 13 ships.

Output: Human-verified AI field placement on a real document. Phase 13 complete.

<execution_context> @/Users/ccopeland/.claude/get-shit-done/workflows/execute-plan.md @/Users/ccopeland/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/13-ai-field-placement-and-pre-fill/13-RESEARCH.md @.planning/phases/13-ai-field-placement-and-pre-fill/13-01-SUMMARY.md @.planning/phases/13-ai-field-placement-and-pre-fill/13-02-SUMMARY.md @.planning/phases/13-ai-field-placement-and-pre-fill/13-03-SUMMARY.md Task 1: Run unit tests and TypeScript build check Run the full test suite for the AI coordinate conversion and confirm TypeScript compiles clean:

cd /Users/ccopeland/temp/red/teressa-copeland-homes
npx jest src/lib/pdf/__tests__/ai-coords.test.ts --no-coverage --verbose
npx tsc --noEmit

If any test fails:

• Re-read the formula in aiCoordsToPagePdfSpace against FieldPlacer.tsx lines 289-290
• The expected values in the test file are authoritative — fix the implementation, not the tests
• Re-run until GREEN

If TypeScript errors:

• Fix them (likely missing prop types or import errors)
• Re-run npx tsc --noEmit until clean

Do NOT proceed to the checkpoint task until both commands pass cleanly. cd /Users/ccopeland/temp/red/teressa-copeland-homes && npx jest src/lib/pdf/tests/ai-coords.test.ts --no-coverage --verbose && npx tsc --noEmit All aiCoordsToPagePdfSpace test cases PASS. TypeScript compiles with no errors. Ready for human verification.

Task 2: Human E2E verification of AI field placement Human verifies the complete AI auto-place feature end-to-end on a real document at localhost:3000. Complete AI field placement feature: - "AI Auto-place Fields" button (violet) in PreparePanel for all Draft documents - POST /api/documents/[id]/ai-prepare route that extracts PDF text, calls GPT-4o-mini, converts coordinates, writes fields to DB - FieldPlacer re-fetches from DB after AI placement (aiPlacementKey increment) - Text fields pre-filled from client profile (name, property address) where available - Unit test: aiCoordsToPagePdfSpace Y-axis flip verified for US Letter 612×792 pts Before running this test, ensure: - `.env.local` in the teressa-copeland-homes directory has `OPENAI_API_KEY=sk-...` set - `npm run dev` is running at localhost:3000

Step 1: Verify the "AI Auto-place Fields" button appears

• Open any Draft document in the portal: http://localhost:3000/portal/documents/[any-draft-docId]
• Confirm the violet "AI Auto-place Fields" button is visible in the PreparePanel (above the gray "Preview" button)
• Confirm it is NOT visible for non-Draft documents (Sent/Signed)

Step 2: Test AI auto-place on a simple document

• Choose a Draft document with a PDF that has visible form fields (any uploaded PDF)
• Click "AI Auto-place Fields"
• Expected: Button shows "AI placing fields..." during the request
• Expected: After completion, field overlays appear on the PDF canvas representing AI-placed fields
• Confirm field overlays appear — even if placement is imperfect, at least some fields should appear

Step 3: Verify field editability (AI-01 success criterion)

• Click on one of the AI-placed text field overlays — confirm it selects (blue ring appears)
• Try moving a field to a different position — confirm drag-and-drop works
• Try deleting a field (click x) — confirm it deletes
• Confirm the remaining fields still show after delete

Step 4: Verify text pre-fill (AI-02)

• If the document has an assigned client with a name and property address, open that document
• Click "AI Auto-place Fields"
• After completion, check the PreparePanel quick-fill area — click a text field
• Expected: The field value is already populated with client name or property address (if AI detected a matching field)
• Note: AI may not always pre-fill — this is best-effort. As long as the mechanism works when AI returns a prefillValue, it passes.

Step 5: Verify Y-axis coordinate accuracy (AI-01 success criterion)

• Place a known field manually at 10% from top on a real PDF, note its visual position
• Use AI auto-place on the same PDF
• Expected: AI-placed fields should appear at roughly correct vertical positions (not inverted/flipped to bottom)
• If fields appear at bottom when they should be at top, flag as a coordinate bug (do not approve)

Step 6: Verify preview and prepare still work after AI placement

• After AI auto-place, click "Preview" — confirm preview generates successfully
• Confirm the preview PDF shows the AI-placed fields
• Note: You do NOT need to click "Prepare and Send" for this verification

Step 7: Verify error state

• Temporarily set an invalid OPENAI_API_KEY in .env.local (e.g., OPENAI_API_KEY=invalid)
• Restart dev server, click "AI Auto-place Fields"
• Expected: An error message appears in PreparePanel (red text) — it should NOT crash the page
• Restore the correct API key afterward MISSING — this is a human-verify checkpoint; automated verification is Step 7 above (error state test) Human approves all 7 verification steps. AI-01 and AI-02 verified. Phase 13 complete. Type "approved" if all 7 steps pass. Describe any issues (especially Y-axis inversion in Step 5 or field editability failures in Step 3) and I will diagnose and fix.

Known acceptable limitations:

• AI may not place fields on every form perfectly — imprecise positions are acceptable as long as they are in the correct vertical region
• AI may not pre-fill text fields if it does not detect matching labels — that is acceptable
• Very long PDFs (20+ pages) may take 10-20 seconds — that is acceptable

Blocking failures (do NOT approve):

• Fields appear at inverted Y positions (Step 5) — this means aiCoordsToPagePdfSpace has a bug
• Fields cannot be moved or deleted after AI placement (Step 3)
• Page crashes or 500 error without user-visible error message
• "AI Auto-place Fields" button does not appear for Draft documents (Step 1)

- All aiCoordsToPagePdfSpace unit tests pass - TypeScript compiles clean: npx tsc --noEmit - AI Auto-place button visible in PreparePanel for Draft documents - AI placement populates FieldPlacer with field overlays from DB - Fields are movable/resizable/deletable after AI placement - Text pre-fill from client profile works when AI detects matching fields - Error state visible (not a crash) when API key is missing/invalid - Human approved all 7 verification steps

<success_criteria>

• Unit tests green (aiCoordsToPagePdfSpace)
• TypeScript clean build
• Human approves Steps 1-7:
  • AI Auto-place button appears for Draft docs
  • Fields appear on canvas after AI placement
  • Fields are editable (move, resize, delete)
  • Y-axis coordinates are correct (not inverted)
  • Preview and prepare-and-send still work after AI placement
  • Error state shown (not crash) when API key invalid
• AI-01 satisfied: one-click button places field types from PDF analysis
• AI-02 satisfied: text fields pre-filled with client data where AI detects match
• Phase 13 complete — v1.1 Smart Document Preparation milestone fully shipped </success_criteria>

After completion, create `.planning/phases/13-ai-field-placement-and-pre-fill/13-04-SUMMARY.md`