Initial commit

skills/filling-pdf-forms/references/Populating-Fillable.md

@@ -0,0 +1,100 @@
+# Populating Fillable PDF Forms
+
+<purpose>
+After collecting data via Chatfield interview, populate fillable PDF forms with the results.
+</purpose>
+
+## Process Overview
+
+```plantuml
+@startuml Populating-Fillable
+title Populating Fillable PDF Forms
+start
+:Parse Chatfield output;
+:Read <basename>.form.json for metadata;
+:Create <basename>.values.json;
+repeat
+  :Validate .values.json
+  (see validation checklist);
+  if (All checks pass?) then (yes)
+  else (no)
+    :Fix .values.json;
+  endif
+repeat while (All checks pass?) is (no)
+->yes;
+:Execute fill_fillable_fields.py;
+:**✓ PDF POPULATION COMPLETE**;
+stop
+@enduml
+```
+
+## Process
+
+### 1. Parse Chatfield Output
+
+Run Chatfield with `--inspect` for a final summary of all collected data:
+```bash
+python -m chatfield.cli --state='<basename>.chatfield/interview.db' --interview='<basename>.chatfield/interview.py' --inspect
+```
+
+Extract `field_id` and the proper value for each field.
+
+### 2. Create `.values.json`
+
+Create `<basename>.values.json` in the `<basename>.chatfield/` directory with the collected field values:
+
+```json
+[
+  {"field_id": "name", "page": 1, "value": "John Doe"},
+  {"field_id": "age_years", "page": 1, "value": 25},
+  {"field_id": "age_display", "page": 1, "value": "25"},
+  {"field_id": "checkbox_over_18", "page": 1, "value": "/1"}
+]
+```
+
+**Value selection priority:**
+- **CRITICAL**: If a language cast exists for a field (e.g., `.as_lang_es`, `.as_lang_fr`), **always prefer it** over the raw value
+- This ensures forms are populated in the form's language, not the conversation language
+- The language cast name matches the form's language code (e.g., `as_lang_es` for Spanish forms)
+- Only use the raw value if no language cast exists
+
+**Boolean conversion for checkboxes:**
+- Read `.form.json` for `checked_value` and `unchecked_value`
+- Typically: `"/1"` or `"/On"` for checked, `"/Off"` for unchecked
+- Convert Python `True`/`False` → PDF checkbox values
+
+### 3. Validate `.values.json`
+
+**Before running the population script**, validate the `.values.json` file against the validation checklist below:
+- Verify all field_ids from `.form.json` are present
+- Check checkbox values match `checked_value`/`unchecked_value` from `.form.json`
+- Ensure numeric fields use numbers, not strings
+- Confirm language cast values are used when available
+
+If validation fails, fix the `.values.json` file and re-validate until all checks pass.
+
+### 4. Populate PDF
+
+Once validation passes, run the population script (note, the `scripts` directory is relative to the base directory for this skill):
+
+```bash
+python scripts/fill_fillable_fields.py <basename>.pdf <basename>.chatfield/<basename>.values.json <basename>.done.pdf
+
+## Validation Checklist
+
+<validation_checklist>
+**Missing fields:**
+- Check that all field_ids from `.form.json` are in `.values.json`
+- Verify field_id spelling matches exactly
+
+**Wrong checkbox values:**
+- Check `checked_value`/`unchecked_value` in `.form.json`
+- Common values: `/1`, `/On`, `/Yes` for checked; `/Off`, `/No` for unchecked
+
+**Type errors:**
+- Ensure numeric fields use numbers, not strings: `25` not `"25"`
+- Ensure boolean checkboxes use proper values from `.form.json`
+
+**Language translation (for translated forms):**
+- Ensure language cast value is used when it exists (e.g., `as_lang_es` for Spanish forms)
+</validation_checklist>