# Phase 12: Orders/Invoices & Company Matching - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-07-11
**Phase:** 12-orders-invoices-company-matching
**Areas discussed:** Match confidence threshold, No-match & ambiguous-candidate handling

---

## Match Confidence Threshold

| Option | Description | Selected |
|--------|-------------|----------|
| Exact name match only | Only auto-link on byte-identical names (case/whitespace-insensitive). Safest but likely means most companies land in review. | |
| High-confidence fuzzy match | Auto-link when similarity clears a high bar (e.g. ≥90-95%), covering near-identical names. | ✓ |
| You decide | Planner picks a threshold based on research. | |

**User's choice:** High-confidence fuzzy match

**Follow-up: threshold tuning approach**

| Option | Description | Selected |
|--------|-------------|----------|
| Set an initial number, tune later | Planner picks ~90-95% as a starting point, documented for later adjustment. | |
| Be conservative — fewer auto-matches | Bias toward flagging borderline cases; accept more manual review since this feeds cost/billing reconciliation. | ✓ |
| You decide | No strong preference. | |

**User's choice:** Be conservative — fewer auto-matches
**Notes:** User explicitly prioritized avoiding wrong auto-links over reducing review burden, since this data feeds cost/billing reconciliation.

**Follow-up: duplicate/tie edge case**

| Option | Description | Selected |
|--------|-------------|----------|
| Yes — always flag on any tie | Even an exact name match gets flagged if ambiguous against multiple same/similar-named Autotask companies. | ✓ |
| No — exact match always wins | Exact string equality is strong enough signal on its own, even with a second similarly-named company present. | |

**User's choice:** Yes — always flag on any tie
**Notes:** Reinforces the conservative stance — never silently pick between look-alike companies (e.g. franchise locations).

---

## No-Match & Ambiguous-Candidate Handling

| Option | Description | Selected |
|--------|-------------|----------|
| Flag with an empty candidate list | Still create a review row with an empty candidate array for true no-match cases, so it surfaces in the admin queue. | ✓ |
| You decide | Planner decides mechanics as long as PAX8-11 (never silently dropped) is satisfied. | |

**User's choice:** Flag with an empty candidate list

**Follow-up: ambiguous-candidate count**

| Option | Description | Selected |
|--------|-------------|----------|
| Top 3 | Cap review candidates at the 3 highest-scoring Autotask companies, matching `device_link_review` precedent. | ✓ |
| All above a "plausible" floor | Show every candidate clearing a low relevance floor, regardless of count. | |
| You decide | Planner picks a reasonable cap. | |

**User's choice:** Top 3

**Follow-up: re-scoring cadence for unresolved reviews**

| Option | Description | Selected |
|--------|-------------|----------|
| Re-score every sync until resolved | Keep re-evaluating unresolved PAX8 companies each full sync; resolved matches still never overwritten. | ✓ |
| Match once, don't re-touch until resolved | Leave flagged companies alone until an admin resolves them — simpler, stable candidate list between admin visits. | |

**User's choice:** Re-score every sync until resolved
**Notes:** Candidates can improve over time (e.g. a renamed/newly-created Autotask company scores better later) without requiring a manual re-trigger. Does not affect SC#4's idempotency guarantee for already-resolved matches.

---

## Claude's Discretion

- Exact numeric fuzzy-match threshold and matching library/approach (e.g. Postgres `pg_trgm` vs. a JS similarity library) — user wants "conservative," not a specific number; planner researches and documents the chosen value.
- Company name normalization nuances (legal suffixes like LLC/Inc/Corp, punctuation, abbreviations) — gray area was surfaced but not selected for discussion this session.
- Orders/invoices historical lookback window (full history vs. bounded window) — gray area was surfaced but not selected for discussion this session; `migrations/091`'s inline comment indicates full history was the original intent, to be confirmed during research.

## Deferred Ideas

None — discussion stayed within Phase 12's scope. No new capabilities were proposed; the two undiscussed gray areas above were left to Claude's discretion within this phase, not deferred to a future phase.
