---
title: "Teach Matching Scope"
slug: teach-matching-scope
section: Placement & Matching
status: draft
description: "Scoping spec for delivering functional Teach USA matching on the Globus P7 engine, grounded in a comparison against the Teacher Lounge high-level prototype"
last-updated: 2026-10-07
---

# Teach Matching Scope

Scoping spec for delivering functional Teach USA matching on the Globus P7 engine, grounded in a comparison against the Teacher Lounge high-level prototype

## Overview

Teacher Lounge scoping starts with the matching engine. The high-level prototype (the `Global_Feature` branch of the portal prototype) delivers TEACH matching as an **LLM scoring service**: the OpenAI-backed TEACH AI Matching Service parses a pasted job description into structured requirements, scores each candidate on subject match, education match, certification alignment, cultural fit, experience, and overall suitability, classifies results into four recommendation levels (`highly_recommended`, `recommended`, `conditional`, `not_suitable`), and generates a personalized prose explanation per candidate. Candidates come from the external Hanover talent pool; recommendations surface on a suggested-teachers dashboard and flow through a reserve → interview → shortlist → hire/decline loop, with AI adoption analytics tracking which hires originated from AI suggestions.

Globus's delivered P7 engine is the opposite architecture: a **deterministic, field-driven ScoringEngine** reading `requirement_field_definitions`, applying hard filters, weighted soft-scoring dimensions, and bilateral preference matching under per-program weight profiles that must sum to 1.0, with dismissal tracking, full per-dimension score transparency, and the `/matching` console (eligible and ineligible tabs) plus the `/matching/configuration` page. Today Teach USA exists in that engine **only as a weight-profile column** — there are no Teach-specific requirement field definitions, no supply-side teaching-qualification facts to score against, and no host-facing surface that consumes match output.

This page records the comparison, enumerates the gaps between the two, states what is deliberately not carried over from the prototype, and proposes a delivery sequencing with an explicit ownership split between Globus P7 (the engine) and P11.5 / Teacher Lounge (the consumption surfaces). Downstream Globus and Teacher Lounge tickets are filed from this spec once approved.

> **The prototype is a behavioral reference, not an implementation source**
>
> The prototype demonstrates *what hosts need from Teach matching* — subject/grade/certification/education fit, readable explanations, a suggestion-to-hire loop, and adoption measurement. It does not dictate *how* Globus computes matches. Globus keeps its deterministic, explainable, configurable engine; the prototype's LLM architecture is explicitly not adopted (see Deliberately Not Carried Over below).

## Globus vs Prototype Comparison

| Axis | Globus P7 (delivered) | Prototype (`Global_Feature` branch) |
| --- | --- | --- |
| Scoring approach | Deterministic weighted scoring: hard filters + soft dimensions (0.0–1.0 each) + bilateral preference matching; reproducible per-dimension breakdown for every score | LLM scoring (OpenAI TEACH AI Matching Service): subject/education/certification/cultural-fit component scores, 0–100 overall, four recommendation levels; rule-based fallback when OpenAI is unavailable |
| Requirement source | Structured `job_orders.requirements` validated against `requirement_field_definitions` at submit time | Unstructured job-description text parsed by AI into requirements (subjects, grade level, education, certification, English level, special skills) |
| Candidate source | Globus applicants/applications (single source of truth, applicant-vs-application split) | External Hanover API talent pool, "the primary source of potential hires for all programs" |
| Eligibility separation | Strict layering: Rules Engine (Layer 5) decides program/season eligibility before matching (Layer 7) ever scores; matching never re-implements eligibility | No separate eligibility layer — suitability, eligibility, and fit are blended into one AI score and recommendation level |
| Configurability & governance | Per-program weight profiles (sum = 1.0, enforced at write time), weights editable in `/matching/configuration` and field definitions in the program edit screen's Requirement Field Definitions panel; matching-profiles PRD adds versioned draft/publish/archive governance | Prompt- and code-defined behavior; no operator-facing configuration surface, no weight governance, no publish gate |
| Teach-specific logic | A Teach USA weight-profile column only — no Teach field definitions, no subject/grade/certification dimensions, no teaching-qualification facts | Rich Teach semantics: inclusive subject matching (a general elementary teacher can teach multiple elementary subjects), bilingual credit, grade-level fit, certification alignment, education-level match |
| Consumption workflow | Staff-facing only: matching dashboard, match breakdown panel, dismissals — no host-facing surface | Host-facing end to end: suggested-teachers dashboard cards (score + prose explanation) → reserve → schedule interview → shortlist → hire/decline with structured outcome capture and AI adoption analytics |

## Gap List — What a Functional Teach Engine Still Needs

Each gap below is a discrete scoping unit. Together they take Teach USA from "a weight column" to a functional matching capability with a host-facing consumption loop.

### Teach Demand-Side Field Definitions

The P7 Fields tab has no Teach entries. Required `requirement_field_definitions` for the Teach USA program:

| Field | Notes |
| --- | --- |
| Subjects | List-typed, with a **transferable-subject taxonomy** carrying the prototype's inclusive semantics deterministically: a general elementary qualification satisfies the elementary subject family; explicit subject-transferability edges (e.g. Mathematics → General Science eligibility where policy allows) are data, not code |
| Grade level | Enum (Elementary K–5, Middle School 6–8, High School 9–12); hard or soft per job order |
| Certification | Teaching certification/registration requirement; must-have capable, verification-aware |
| Education level | Minimum degree level (e.g. Bachelor's in Education or subject field); scored via the existing qualifications-style extractor family |

Bilingual/language capability continues to use the existing Language dimension — no new field, but the Teach weight profile should be revisited once real dimensions replace the placeholder column.

### Teach Supply-Side Qualification Facts

Scoring the fields above requires structured applicant facts: per-qualification education records with stable IDs, completion status, and verification state, plus teaching-registration data (licence type, status, authorised subjects and grade levels). The `education_records` and `teaching_registrations` tables now exist, and are what the Education & Teaching Qualifications spec delivers (together with verified document requirements). Teach matching therefore has a **hard dependency** on that spec's Phase 1–2 tickets: subject, certification, and education-level dimensions score against verified structured records, not free-text answers. Until matching reads those records,  Teach dimensions can only score 0.0-with-missing-data-policy.

### Teach Eligibility Gating via the Rules Engine

Consistent with the Layer 5/7 separation, Teach program eligibility (e.g. two-year teaching-experience requirement, degree prerequisites, English level, registration validity where mandatory) is authored as Rules Engine rule definitions, **not** as matching hard filters. Matching receives only Rules-Engine-eligible applicants; the prototype's blended "suitability includes eligibility" model is explicitly rejected. New Teach rules follow the existing typed-condition pipeline and compliance queues.

### Teacher Lounge Consumption & Feedback API Contract

The prototype's reserve → interview → shortlist → hire loop is the consumption surface Teach matching needs — and Globus has no host-facing matching API. Required: a contract by which the Teacher Lounge host portal (P11.5 family) reads ranked, explainable match suggestions for a school's job orders and writes back host actions (viewed, dismissed-with-reason, reserved, interview scheduled, shortlisted, outcome recorded). The engine stays Globus-authoritative; Teacher Lounge is a consumer. Dismissals from the host side reuse the existing `match_dismissals` model rather than a parallel table.

### Host-Readable Explanation Rendering

Staff see the per-dimension raw/weight/contribution breakdown; hosts should not. The gap is a **deterministic explanation renderer** that translates the existing score breakdown into host-readable statements ("Meets required Grade 3–5 experience; certified in Mathematics; bilingual Spanish") — template-driven from factor outcomes, not LLM prose. This preserves the prototype's explanation UX while keeping every sentence traceable to a scored factor.

### Match-Source Attribution Analytics

The prototype tracks whether each hire originated from an AI suggestion (`wasAiSuggested`, adoption dashboards, weekly suggest-rate reports). The Globus equivalent is **match-source attribution**: tagging reservations/placements with whether they originated from an engine suggestion vs manual sourcing, and rolling up suggestion-adoption and outcome metrics per school/season. Persisted `match_evaluations` rows (matching-profiles PRD) are the natural anchor; the analytics surface itself is a reporting concern, not an engine concern.

### Interview-Outcome Capture Ownership

The prototype captures structured interview outcomes (category ratings, decision, decline reasons including English proficiency). Ownership must be settled: the **interview/outcome workflow and its data live in Globus** (they are placement-lifecycle facts other layers consume), while **Teacher Lounge renders the capture UX** through the consumption contract above. Outcome data feeds match-source attribution and, later, weight-tuning evidence — it must not be trapped in the portal.

## Deliberately Not Carried Over

| Prototype feature | Why it is dropped |
| --- | --- |
| LLM job-description parsing | Globus demand is structured at the source: job orders carry validated `requirements` against field definitions. There is no unstructured-text intake to parse; adding one would undermine submit-time validation |
| Non-deterministic (LLM) scoring | The engine's contract is reproducible, auditable, per-dimension scoring under governed weights. LLM scores cannot be replayed, impact-tested in the harness, or gated by the publishing validation gate; the four recommendation levels are replaced by transparent numeric scores with configurable thresholds if banding is needed |
| Hanover as candidate source | Globus applicants/applications are the single source of truth for supply. No external talent-pool dependency is introduced; returner and qualification signals already key off the applicant-vs-application model |

## Proposed Delivery Sequencing

Ownership is split: **Globus P7 owns the engine**, **P11.5 / Teacher Lounge owns consumption surfaces**. Sequencing respects the hard dependency on the Education & Teaching Qualifications spec.

| # | Increment | Owner | Depends on |
| --- | --- | --- | --- |
| 1 | Teach demand-side field definitions + transferable-subject taxonomy seeded via the program edit screen's Requirement Field Definitions panel | Globus P7 | — |
| 2 | Teach supply-side qualification facts | Globus (P11B Education & Teaching Qualifications tickets, already chained) | Approved spec delivery |
| 3 | Teach eligibility rule definitions | Globus Rules Engine (P3) | — (parallel with 1–2) |
| 4 | Teach scoring dimensions wired: subject / grade / certification / education extractors + real Teach weight profile rebalance (sum = 1.0) | Globus P7 | 1, 2 |
| 5 | Host consumption & feedback API contract (suggestions read, host actions write-back, dismissal reuse) | Contract co-owned: Globus P7 (server) + Teacher Lounge (client) | 4 |
| 6 | Host-readable explanation renderer | Globus P7 | 4 |
| 7 | Teacher Lounge suggested-teachers surface + reserve/interview/shortlist/outcome UX | P11.5 / Teacher Lounge | 5, 6 |
| 8 | Interview-outcome capture (Globus-owned data, portal-rendered UX) | Globus + Teacher Lounge | 5 |
| 9 | Match-source attribution analytics | Globus reporting | 7, 8 |

> **Ticket filing is a follow-up**
>
> This page is the scoping source of truth. Asana tickets on the P7 board (engine increments) and the Teacher Lounge / P11.5 boards (consumption increments) are filed from it after approval — not as part of this spec.

## Related Pages

- [Matching Engine](/docs/matching-engine) — the delivered P7 engine and the matching-profiles configuration layer this scope builds on.
- [Education & Teaching Qualifications](/docs/education-teaching-qualifications) — the approved-not-built supply-side facts Teach dimensions depend on.
- [Rules Engine](/docs/rules-engine) — where Teach eligibility gating is authored.
- [Job Orders](/docs/job-orders) — the demand-side structure Teach field definitions extend.