Word Cross-Reference & Numbering Field Triage

When to use / when not to use

Use when:

• Customer reports reference numbers or clause numbering “wrong” in SpotDraft
• Support reproduces fix after F9 or full-document Update Fields
• Discussion touches template workflow_id, Legal-updated numbering, PDF vs DOCX for send/sign

Do not use for:

• OnlyOffice list numbering glitches on uploaded PDF/TPP (no Word fields) → pdf-upload-visual-artifacts
• Computation / metadata driving display numbers → contract-computation-null-propagation
• Litera compare failures → litera-version-compare-triage

System flow (high level)

Template DOCX (Word fields: SEQ, REF, STYLEREF, …)
  → cf-exporter / templater merges variables → Contract version DOCX
  → OnlyOffice loads DOCX → user sees numbers (fields may be stale until updated)
  → Optional: export / convert to PDF for email or signing → field update + reflow may change appearance

Useful identifiers:

Investigation workflow

Step 1: Reproduce the “F9” signal

1. Open the contract in the editor as the customer does.
2. Note clause / REF values before any bulk selection.
3. Select all → F9 (or OnlyOffice equivalent Update fields).
4. If numbers snap to correct → treat as field refresh / display pipeline, not necessarily wrong merge data.

Document in ticket: Loom or screenshots before/after (incident used Loom — use as format example only).

Step 2: Compare artifacts (backend vs UI)

1. Download current contract DOCX from SpotDraft (admin or product flow).
2. Open in desktop Word → File → Info → Edit links / right-click fields → Update field if needed.
3. Compare to what OnlyOffice showed before F9.
4. If Word-on-desktop matches post-F9 view → UI refresh issue; if Word also wrong → template or merge issue.

Rootly mitigation for one production incident stated references are correct in the backend with a frontend display / field-refresh angle — verify per contract before asserting.

Step 3: PDF / signing path (Sanket’s note from incident thread)

When customer uses PDF for signing or distribution:

• DOCX → PDF conversion often causes Word to update fields, reflow text, change margins, and refresh cross-references — reference numbers can change vs in-editor DOCX.
• Customer may refuse PDF (e.g. partners export PDF → Word); CS should align with Legal and product on tradeoffs — there is no silent “always identical numbering” guarantee across DOCX and PDF when fields are involved.

Step 4: Template / Legal ops

1. Confirm which template version is live (workflow_id / republish).
2. Legal Ops may need to simplify numbering (e.g. reduce fragile REF chains) or adjust how SEQ/REF are used so refresh order matters less.
3. Action item from incident: check whether references can be refreshed inside Word at template authoring time; connect Legal Ops for template mitigation.

Step 5: Logs & BQ (optional)

• This class of issue is rarely confirmed via application error logs alone.
• Use contract-lookup / BQ on contracts_v3_contractversion to confirm version, docx_version, timestamps — not to prove field staleness.

Mitigation options (pick with customer + Legal)

CS note from thread: Avoid promising hacky workarounds; prefer clear vendor/editor behavior + Legal template path when PDF is rejected.

Confirm / disprove

Escalation triggers

• Many workflows broken after a release → regression in exporter or OnlyOffice integration → #pod-editor (or owning pod).
• Single customer, F9 pattern, backend file correct → mitigation + template; permanent auto-refresh is a feature request.
• Customer blocked on PDF policy → PM / CS + Legal, not L2 alone.

Related incidents & Jira

Connections to other skills

• contract-lookup — {contract_id} → versions, template, workspace.
• pdf-upload-visual-artifacts — Numbering visual issues on uploaded PDFs / TPP / Chrome Print — different entry point.
• contract-signing-triage — If failure is cannot generate PDF or sign task errors, not wrong clause numbers.

Operational note

Run BigQuery queries one at a time if using BQ MCP (repo README — parallel calls can 500).