Note (2026-04-24): After this document was written, legal_entity was renamed to tenant and the old tenant was renamed to organization. Read references to these terms with the pre-rename meaning.

Debug Match Skill — Design

Problem

When matching produces incorrect results (false positives, false negatives, failed pipelines, bad reconciliation), debugging requires:

1. Fetching the document's entire match cluster from production (all documents, edges, reconciliation)
2. Understanding why matching behaved the way it did

There is no tooling to fetch a full cluster from prod. The existing bb debug:fetch-document only fetches a single document in isolation. And there is no skill to guide the investigation.

Solution

Two pieces:

1. bb debug:fetch-match-cluster <doc-id> — a bb task that fetches a document's full match cluster from production into local
2. /debug-match skill — orchestrates fetching, gathers context from local DB, then delegates investigation to an orcha-workers subagent using the systematic-debugging skill

Skill Interface

/debug-match <doc-id> [problem description]
/debug-match <doc-id-1> <doc-id-2> [problem description]

• One doc ID: inspect the document's existing cluster (wrong match, failed matching, bad reconciliation)
• Two doc IDs: investigate why two documents didn't match (false negative), or why one matched incorrectly instead of the other

UUIDs are detected by format; everything else is the problem description.

bb debug:fetch-match-cluster

What it fetches from prod (via nREPL)

Given a document ID:

1. The document row — get its cluster_id
2. If cluster_id exists:
   • All documents in the cluster (SELECT * FROM document WHERE cluster_id = ?)
   • All document_match edges within the cluster
   • The document_cluster row (including reconciliation JSONB and reconciled_at)
3. If no cluster_id: just the document itself (unmatched)
4. Ingestions for every document in the cluster

Returns a map:

{:document     {...}                        ;; the requested doc
 :cluster      {...}                        ;; document_cluster row, nil if unmatched
 :cluster-docs [{...} ...]                  ;; all docs in cluster
 :match-edges  [{...} ...]                  ;; all document_match rows
 :ingestions   {<doc-id> [{...} ...] ...}}  ;; ingestions keyed by document id

Local insert

For each document in the cluster:

• Insert document row (with dev-seed legal entity)
• Insert ingestion rows
• Download S3 files (PDFs, transcriptions) from prod, upload to local S3

Additionally:

• Insert document_cluster row (with reconciliation data)
• Set cluster_id on all documents
• Insert all document_match edge rows

Conflict handling

If any document already exists locally, prompt to replace (same UX as debug:fetch-document).

Shared utilities — scripts/debug_common.clj

Extract from debug_fetch_document.clj into a shared namespace:

• SSM/nREPL: get-instance-id, start-port-forward!, wait-for-port, nrepl-eval
• S3: prod-s3-download!, local-s3-upload!
• Local DB inserts: insert-document!, insert-ingestions!, document-exists?, delete-local-document!
• Helpers: unqualify-keys, cast-special-fields, prompt-yes-no
• Config constants: local-db, prod-profile, prod-region, S3 buckets, ports, etc.

debug_fetch_document.clj gets refactored to use debug-common. debug_fetch_match_cluster.clj uses the same shared namespace plus adds cluster/match/reconciliation insert logic.

Skill Flow

/debug-match <args>
    |
    v
[Parse args: extract doc IDs + problem description]
    |
    v
[For each doc ID: check local DB for document + cluster data]
    |
    v
[If missing: run `bb debug:fetch-match-cluster <doc-id>`]
    |  (handle auth errors: prompt `aws sso login`)
    v
[Query local DB for full context:
  - All documents in cluster(s)
  - All match edges (scores, method, evidence, confidence)
  - Reconciliation data
  - Matching status/error fields
  - Normalized fields (counterparty, references)]
    |
    v
[Spawn orcha-workers subagent with:
  - Gathered cluster data
  - User's problem description
  - Doc IDs and scenario type (one-doc vs two-doc)
  - Instruction to use systematic-debugging skill]

The skill does not prescribe what the subagent investigates. It ensures the right data is local, gathers it, and delegates. The subagent reads the matching source code and follows systematic-debugging to find the root cause.

Decisions