openplanter

OpenPlanter — Investigation Methodology Skill

Epistemic framework for cross-dataset investigation, entity resolution, and evidence-backed analysis. Extracted from the OpenPlanter recursive investigation agent and enriched with professional OSINT tradecraft (Admiralty System, ACH, FollowTheMoney schema, intelligence cycle methodology).

Claude Code already has the tools. This skill provides the methodology.

When to Use

• Cross-referencing heterogeneous datasets (corporate registries, campaign finance, lobbying, property records, contracts)
• Entity resolution across datasets with inconsistent naming
• Building evidence chains with provenance and confidence tiers
• Structured OSINT investigations requiring epistemic discipline
• Any analysis where claims need to trace to cited source records

Quick Start

# 1. Initialize workspace
python3 ~/.claude/skills/openplanter/scripts/init_workspace.py /path/to/investigation

# 2. Drop datasets into datasets/
cp campaign_finance.csv lobbying.json corporate_registry.csv /path/to/investigation/datasets/

# 3. Write an investigation plan
# → plans/plan.md (see references/output-templates.md for plan template)

# 4. Resolve entities across datasets
python3 ~/.claude/skills/openplanter/scripts/entity_resolver.py /path/to/investigation

# 5. Cross-reference linked entities
python3 ~/.claude/skills/openplanter/scripts/cross_reference.py /path/to/investigation

# 6. Validate evidence chains
python3 ~/.claude/skills/openplanter/scripts/evidence_chain.py /path/to/investigation

# 7. Score confidence
python3 ~/.claude/skills/openplanter/scripts/confidence_scorer.py /path/to/investigation

Investigation Methodology

Epistemic Discipline

Assume nothing about the environment until confirmed firsthand. These principles prevent the most common investigation failures:

1. Ground truth comes from files, not memory. Read actual data before modifying it, and read actual error messages before diagnosing. Model memory of data structure is unreliable—reading the file takes seconds, recovering from a wrong assumption takes minutes.
2. Empty output is ambiguous. If a command returns empty, cross-check with ls -la and wc -c before concluding a file is actually empty, because output capture mechanisms can silently lose data.
3. Success does not mean correctness. A command that "succeeds" may have done nothing. Check actual outcomes, not just exit codes. After downloading, verify with ls and wc -c. After extraction, verify expected files exist.
4. Verify round-trip correctness. After any data transformation (parsing, linking, aggregation), check the result from the consumer's perspective—load the output, spot-check records, verify row counts. Transformations that silently drop records are the most common source of wrong conclusions.
5. Three failures = wrong approach. If a command fails 3 times, change strategy entirely. Repeating an identical command expecting different results wastes context window.
6. Produce artifacts early. Write a working first draft of findings as soon as the requirements are clear, then iterate. An imperfect deliverable beats a perfect analysis with no output. If 3+ steps have passed without writing any output, stop and write—even if incomplete.

For the full epistemic framework (including data ingestion rules and hard rules from OpenPlanter's prompts.py), see references/investigation-methodology.md.

Entity Resolution Protocol

Pipeline: Normalize → Block → Compare → Score → Cluster → Review

Adapted from OpenPlanter's prompts.py, enriched with Middesk, OpenSanctions, and ICIJ patterns.

1. Normalize — Apply canonical key transformation: Unicode NFKD + diacritic stripping, case folding, legal suffix canonicalization (LLC/Inc/Corp/Ltd → canonical forms), punctuation removal, ampersand normalization (& → and). See references/entity-resolution-patterns.md for complete normalization tables and suffix maps.

1. Block — Reduce O(N^2) comparisons using blocking keys: first 3 characters of normalized name + state/jurisdiction, phonetic key (Soundex/Double Metaphone), token overlap via inverted index.

1. Compare — Pairwise similarity with cascading checks: real_quick_ratio() → quick_ratio() → ratio(). Use autojunk=False for entity names because strings under 200 characters produce false negatives with junk heuristics. Include token set comparison for word-order variants ("Apple Inc" vs "Inc Apple").

1. Score — Multi-signal weighted model:
2. Hard signals: TIN/EIN exact match (1.0), identical phone E.164 (0.8), identical email (0.8)
3. Soft signals: name similarity (0.5), address fuzzy (0.2), state match (0.1)
4. Hard disqualifiers: TIN mismatch when both present (-0.5), country mismatch (-0.5)

1. Cluster — Group via transitive closure using Union-Find. Gate closure so all pairwise scores exceed threshold—this prevents chain errors where A≈B and B≈C but A≉C. Exclude registered agent addresses from triggering transitive closure alone, because thousands of entities share the same registered agent.

1. Review — Flag by confidence band:
2. Score >= 0.85: auto-match (confirmed)
3. Score 0.70-0.84: queue for review (probable)
4. Score 0.55-0.69: include in wide net (possible)
5. Score < 0.55: discard

Evidence Chain Construction

Every claim traces to a specific record in a specific dataset. This is what separates investigation from speculation.

Claim
  └── Evidence Item
        ├── type: document | record | image | testimony
        ├── source_ref → Source
        │     ├── url / file path
        │     ├── collection_timestamp
        │     ├── source_type: primary | secondary | tertiary | official | unofficial
        │     └── reliability_grade: A–F (Admiralty)
        ├── credibility_grade: 1–6 (Admiralty)
        ├── corroboration_status: single | corroborated | contradicted | unresolvable
        └── match_details (if cross-reference)
              ├── fields_matched: [name, address, ein]
              ├── match_type: exact | fuzzy | address-based
              └── link_strength: weakest criterion in the chain

Key principles:

• Distinguish direct evidence (A appears in record X), circumstantial evidence (A's address matches B's address), and absence of evidence (no disclosure found)
• Document every hop in a multi-step chain with source record, linking field, and match quality
• Link strength = weakest criterion in the chain (a chain is only as strong as its weakest link)
• Track source lineage to detect circular reporting—Source B citing Source A is not independent corroboration

Confidence Tiers

Based on the Admiralty System (NATO AJP-2.1), adapted for dataset investigation:

| Tier | Criteria | Required Evidence | Admiralty Equivalent | |------|----------|-------------------|---------------------| | Confirmed | 2+ independent sources with different collection paths; hard signal match (EIN, phone); or official record with verifiable provenance | Independent corroboration required | A1–B1 | | Probable | Strong single source (official record); high fuzzy match (>0.85) on name + address + state; consistent with known patterns | Single strong source acceptable | B2–C2 | | Possible | Circumstantial evidence only; moderate fuzzy match (0.55-0.84); consistent but not yet corroborated; requires additional investigation | Hypothesis supported but not confirmed | C3–D3 | | Unresolved | Contradictory evidence; insufficient data; single weak source; or unable to verify | Cannot determine with available evidence | D4–F6 |

Sherman Kent probability mapping:

• Confirmed ≈ "almost certain" (93-99%)
• Probable ≈ "likely" (75-85%)
• Possible ≈ "chances about even" (45-55%)
• Unresolved ≈ insufficient basis for estimate

Verification Principle

Implementation and verification must be uncorrelated. An agent th