PDF Form Entry And Verification

PDF Form Entry And Verification

Use this skill for fragile PDF forms where misplaced text is worse than leaving a field blank.

Rules

• Start from the clean source PDF whenever possible. Do not stack new fill text on top of a previously dirty filled PDF.
• If the PDF has native fillable text/check fields, use those fields first. Do not use an image/text overlay on a fillable form unless native field filling is impossible or renders incorrectly after QA.
• Render screenshots before and after filling. Inspect the output page images before attaching, uploading, or saying the PDF is ready.
• Treat coordinates as guesses until screenshots prove they are right.
• Center every filled value inside its visible box, underline span, or table cell unless the form explicitly requires a different alignment. For overlays, model the field as a bounding box and use align: "center", max_width, box_height, and valign: "middle" so text does not sit on top of rules.
• Use conservative font sizes. If text barely fits, abbreviate or move to a clean continuation line instead of letting it collide.
• Leave signature, date, notary, witness, broker, agent, carrier, and third-party certification fields blank unless the user explicitly provides the executed value or the signer is present.
• If a form is too risky to fill cleanly under time pressure, send the original blank form with a short signing note rather than a dirty prefilled form.

Workflow

1. Identify the clean source PDF and the exact fields to fill.
2. Render the source pages: python3 scripts/render_pdf_pages.py source.pdf render_source --dpi 200 --grid
3. Fill using a reliable method:
   • For AcroForm/fillable PDFs, fill native text/check/radio fields directly, preserve the fields for signing where appropriate, set appearances/NeedAppearances when the toolchain supports it, and render to verify the text is visible.
   • Use scripts/fill_overlay_pdf.py only for non-fillable PDFs, scanned/image forms, fields that cannot be set natively, or native fills that fail visual QA.
4. Render the filled PDF: python3 scripts/render_pdf_pages.py filled.pdf render_filled --dpi 200 --grid
5. Inspect screenshots with view_image or another visual viewer. Check every filled page, not only page 1.
6. Iterate until text is aligned, centered, readable, and not clipping.
7. Keep the render folder beside the PDF so another reviewer can audit the fill.

Overlay Spec

Use scripts/fill_overlay_pdf.py for image-backed clean fills when native PDF fields are absent or unreliable.

Spec shape:

{
  "dpi": 300,
  "font": "/System/Library/Fonts/Supplemental/Arial.ttf",
  "items": [
    {
      "page": 1,
      "x": 1.25,
      "y": 4.75,
      "text": "Example Company Inc.",
      "size": 10,
      "align": "center",
      "max_width": 2.5,
      "box_height": 0.25,
      "valign": "middle"
    }
  ]
}

Coordinates are inches from the top-left of the page. align may be left, center, or right. Use max_width with center to center text horizontally in a box. Use box_height plus valign: "middle" to center text vertically between the box's top and bottom rule. size is in printer points, not pixels.

Output Standard

When done, report:

• Clean source used.
• Filled PDF path.
• Rendered QA screenshot folder.
• Pages visually checked.
• Any fields intentionally left blank.