Xref

Xref

Resolve cross-references and defined terms in legal documents. When activated, Xref produces an interactive HTML file on the user's Desktop where internal references, defined terms, unresolved items, and external citations are navigable.

Activation

Use this skill when the user asks to:

• "use xref on..."
• "run xref..."
• "resolve the cross-references in..."
• "make this document navigable"
• "link up the references in..."

Respond with:

Xref is active. I'll parse the document, resolve cross-references and defined terms, and save an interactive HTML viewer on your Desktop.

Then run the workflow below.

Supported sources

• Word documents (.docx): primary and most reliable input format
• PDF files (.pdf): supported, but less reliable because PDFs usually lack semantic structure

Tool location

The Xref Python utility is located at:

<plugin_dir>/skills/xref/tools/xref.py

To find the actual path, run:

find ~/.copilot/installed-plugins -name "xref.py" -path "*/xref/*" 2>/dev/null

If not found there, check the cloned repo directory.

First-run setup

Before first use, check that dependencies are installed:

python3 <path-to>/xref.py setup-check

If anything is missing, run the setup script from the xref repo or plugin directory:

bash setup.sh

For optional web tooling:

bash setup.sh --web

Standard workflow

Use the single run command. Do not make the user manage intermediate JSON files.

python3 <path-to>/xref.py run --source "<path-to-document>"

This command:

1. Extracts document structure, including parent sections, subsections, schedules, exhibits, and section body text.
2. Finds internal references, defined-term uses, possible undefined terms, and external citations.
3. Resolves references to targets where possible.
4. Fetches external citation text when available.
5. Builds a self-contained HTML viewer.
6. Saves the output to ~/Desktop/<document-name>-xref.html unless --output is supplied.

Use --output when the user requested a specific destination:

python3 <path-to>/xref.py run \
  --source "<path-to-document>" \
  --output "$HOME/Desktop/<document-name>-xref.html"

Use --no-fetch-external if network access is unavailable or the user wants to avoid external requests:

python3 <path-to>/xref.py run --source "<path-to-document>" --no-fetch-external

Use --compact if the document is large and the user wants a smaller HTML file:

python3 <path-to>/xref.py run --source "<path-to-document>" --compact

Reporting results

After the command finishes, report:

• The saved output path
• Internal references resolved and unresolved
• Defined terms indexed, term uses, and possible undefined terms
• External citations found and fetched
• Any likely drafting issues, such as broken references

Example:

Done. Saved to ~/Desktop/vendor-agreement-xref.html.

Xref indexed 45 sections, resolved 15 internal references, found 2 broken references, indexed 10 defined terms, flagged 2 possible undefined terms, and found 3 external citations.

Error handling

If the document has no extractable text:

This document does not appear to have extractable text. It may be a scanned PDF. Please provide a Word version or OCR the PDF first.

If many references do not resolve:

The section structure appears unusual, so some references could not be matched. The viewer will still open, and unresolved items are listed in the Health tab.

If external citation fetching fails:

Do not fail the task. The viewer still renders the citations and links to official sources when URLs are available. Mention that external citation text was not fetched.

Advanced/debugging commands

Use these only when investigating parser output or debugging Xref itself:

python3 xref.py extract-structure --source "<path-to-document>" > structure.json
python3 xref.py find-references --source "<path-to-document>" > references.json
python3 xref.py resolve-references --structure structure.json --references references.json > resolved.json
python3 xref.py fetch-external --citations '[{"citation_type":"eu_regulation","regulation":"GDPR","article":"28"}]' > externals.json
python3 xref.py build --source "<path-to-document>" --resolved resolved.json --externals externals.json --output ~/Desktop/document-xref.html

Notes

• The viewer works in any modern browser with no server required.
• The source text is not rewritten or summarized.
• Broken internal references and possible undefined terms are surfaced as document health issues rather than silently guessed.
• Touch devices use tap-to-open panels instead of hover.