esign_field_placement v1.0.0

name: esign_field_placement description: "Prepare documents for e-signature: place signature and data fields, route signers in the right order, build reusable templates, and run pre-send QA so envelopes go out once and come back clean. Triggers on: preparing a document for signing, adding signature/initial/date fields, DocuSign envelope setup, signer routing, e-signature templates, audit trail needs."

E-Signature Document Prep

Purpose

Take a raw document (PDF, Word) and produce a signing-ready envelope: every signer has their fields in the right spots, the routing order matches the approval chain, required fields are marked so nothing comes back half-signed, and the audit trail will hold up. Covers field placement, signer routing, reusable templates, and the pre-send QA that keeps envelopes from bouncing.

This skill is platform-neutral but uses DocuSign terminology (tabs, envelopes, recipients) since that is the market leader; every platform (Adobe Acrobat Sign, Dropbox Sign, HelloSign, BoldSign) has the same concepts under different names. See references/field-types.md for the field catalog.

Workflow

1. Define the signing recipe

Before touching the tool, write down the recipe on paper (or in a scratch file):

• Document: file path, page count, which pages need signatures.
• Signers: name, email, role (signs, approves, receives copy), and whether they sign in sequence or in parallel.
• Routing order: numbered steps. Signers sharing a step get the envelope at the same time; the envelope advances only when every signer at that step finishes.
• Fields per signer per page: field type, rough location ("page 4, under the signature line"), required or optional.

A one-signer NDA is a recipe too. Writing it down is what makes templates reusable later.

2. Add recipients and set routing

Add every recipient with name and email, then assign each an action: sign (signs and fills fields), approve (approves without signing), or receive a copy (CC, no action). Set the routing order:

• Sequential: each signer gets their own step number. Use when a later signer must see an earlier signer's signature first (countersignature, manager approval).
• Parallel: signers sharing a step number receive the envelope at the same time. Use when order does not matter; it shortens turnaround.
• Hybrid: groups in sequence, people inside a group in parallel. This covers most business contracts.

Add a subject line and a short personal message ("Hi Maria, here is the revised services agreement we discussed on the call") instead of the platform default; it keeps the request out of spam and gives the signer context. Set a due date when timing matters.

3. Place fields

Drag fields onto each page for the active signer, or assign fields after placing them. One field = one signer. Field types and when to use each are in references/field-types.md. Core rules:

• Every signer who must sign gets a signature field, and pair it with a date signed field so the date is captured at signing time, not typed (typed dates are wrong half the time).
• Mark signature, initials, and any field the document is worthless without as required. Signers cannot complete the envelope with required fields empty.
• Use the smallest field set that does the job. Optional fields get skipped by most signers; if a field matters, make it required, and set auto-navigation to walk the signer through every field so optional checkboxes do not get missed.
• Checkbox groups for mutually exclusive options must NOT be required individually (a signer can only tick one).
• Give formula/calculated fields unique data labels so the formula builder can find them, and restrict inputs to numbers/dates.
• Initials belong beside key clauses (payment terms, term length, liability caps), not on every page. Over-initialing slows signing and trains signers to click through.

Validate the recipe before sending with the bundled checker:

python3 ~/workspace/skills/esign-field-placement/bin/esign-prep-check.py recipe.json

It catches the common failure modes: a signer with no signature field, fields assigned to unknown signers, duplicate field labels, and missing date-signed pairings. A passing check is the gate for step 5.

4. Build (or reuse) a template

When the same document goes out repeatedly (NDAs, engagement letters, offer letters), save the prepared envelope as a template instead of re-placing fields every time:

• Replace real names and emails with placeholder roles ("Client", "Signer 1", "HR Manager"). You fill in the actual people at send time.
• Bake the routing order, field placement, required flags, subject line, and message into the template.
• Version templates when the underlying document changes; retire the old one so nobody sends a stale agreement.

Template recipe steps are in references/templates-and-qa.md.

5. QA, then send

Run the QA checklist in references/templates-and-qa.md plus the checker from step 3, fix what fails, then send. After sending, watch the status dashboard: opened but unsigned after a few days gets one friendly nudge, not a rewrite.

Output Contract

A finished job delivers:

• The document prepared in the signing tool (envelope sent or saved as draft/template), with fields placed, routing set, and QA passed.
• A one-line summary: document name, signer count, routing mode (sequential/parallel/hybrid), and template name if one was created.
• The recipe file (JSON) and checker output kept with the job, so the next run can reuse the template or debug a bounced envelope.

Operating Rules

1. Never invent platform limits or field names. If you are unsure what a platform calls a feature, check its help center; do not guess.
2. Every signer gets their own fields. One shared signature field for two people guarantees a wrong-spot signature.
3. Required is a promise. Mark a field required only when the document is unusable without it; every required field is a reason the envelope can bounce.
4. Do not place fields over existing document text that matters. If the signature block is cramped, widen the document's white space first.
5. This skill does not give legal advice. It prepares documents; whether a signature type is valid for a given document class (deeds, wills, some court filings often need more) is a question for counsel.
6. Keep the audit trail intact: do not edit an envelope after the first signer completes it. If the document must change mid-flight, void the envelope and start a new one.