Entity & Relationship Mapper

Step 2: Check Dependencies

python3 "$SKILL_DIR/scripts/check_dependencies.py"

• Exit 0: all good. Exit 1: packages were installed (proceed). Exit 2: failed (report to user).
• Note: On first run, the spaCy model en_core_web_sm (~12MB) will be downloaded automatically.

Step 3: Run Entity Extraction

Determine the output directory:

• Single file: OUTPUT_DIR="{parent_dir}/{filename_without_ext}_entities"
• Directory: OUTPUT_DIR="{directory_path}/_entity_analysis"

mkdir -p "$OUTPUT_DIR"

python3 "$SKILL_DIR/scripts/map_entities.py" \
  --input "<file_or_directory_path>" \
  --output-dir "$OUTPUT_DIR" \
  [--model en_core_web_sm] \
  [--min-mentions 2]

The script prints JSON to stdout with entity extraction results. Read this output to present findings.

Step 4: Present Entity Summary

Read $OUTPUT_DIR/entity_summary.txt and present key findings:

1. Total entities found with breakdown by type (PERSON, ORG, DATE, MONEY, GPE, LAW, etc.)
2. Most frequent entities - top 10 across all types
3. Key people - most mentioned PERSON entities
4. Key organizations - most mentioned ORG entities
5. Date range - earliest and latest DATE entities detected
6. Financial mentions - summary of MONEY entities

Step 5: Highlight Key Relationships

From the relationship graph data:

1. Most connected entities - entities with the highest centrality scores
2. Entity clusters - groups of entities that frequently co-occur
3. Cross-document entities - entities that appear in multiple documents (if multi-file)

Step 6: Direct User to Outputs

List all generated files with descriptions:

• entity_database.xlsx - Complete entity database with all mentions
• relationship_graph.html - Interactive network graph (open in browser)
• cross_reference_matrix.xlsx - Which entities appear in which documents
• timeline_dates.xlsx - All date entities with surrounding context
• financial_mentions.xlsx - All monetary amounts with context
• entity_summary.txt - Human-readable summary
• entities.json - Structured entity data for programmatic use

Tell the user: "Open relationship_graph.html in your browser to explore the interactive entity network. Nodes are colored by entity type."

Step 7: Offer AI Analysis

Ask: "Would you like me to analyze these entity relationships and their potential legal significance?"

If yes:

1. Read entities.json for the full entity data
2. Provide analysis of:
   • Key parties and their apparent roles
   • Significant dates and their potential relevance
   • Financial amounts and patterns
   • Organizational relationships
   • Cross-document patterns suggesting connections between matters
3. Offer to generate a formal entity analysis report (.docx) using the docx skill

Accuracy and QA (Required)

Anti-hallucination rules (include in ALL subagent prompts):

• Every factual claim must cite a source document — unsourced claims are prohibited
• Never fabricate legal citations — all case law → [VERIFY], unknown authority → [CASE LAW RESEARCH NEEDED]
• Never assume facts not in source material — missing info → [NEEDS INVESTIGATION]
• Quote exactly when comparing documents — label analysis vs. facts distinctly

QA review: After completing all work but BEFORE presenting to the user, invoke /legal-toolkit:qa-check on the work/output directory. Do not skip this step.

Error Handling

• Path not found: Ask user to verify the path
• Unsupported format: Supported types are .pdf, .docx, .txt, .md
• Empty directory: No supported files found -- ask user to check the folder
• Empty extraction: File may be scanned/image-only. Delegate OCR to a subagent: launch an Agent (subagent_type: "general-purpose") with prompt: "Run /legal-toolkit:extract-text on {file_path} and write the extracted text to {parent_dir}/{filename}_ocr.txt." Re-run entity extraction on the OCR output.
• spaCy model not found: Run python3 -m spacy download en_core_web_sm
• Low entity count: Document may not contain recognizable entities; suggest reviewing raw text
• Script not found: Verify the skill is installed (ls $SKILL_DIR/scripts/)