Névsorrend-őr — Tech spec (Instance 2)

checklist.md + 2 ADR + QA skill + végrehajtási prompt — kész az építésre

Master summary — the gist in 30 seconds

TL;DRA terv 4 klaszterre bomlik: A az őr-szkript (Gemini), B a feltöltési kapu, C a 92 K-X lead élő javítása, D a skill + globális szabály. 8 Tier-1 + 2 Tier-2 ellenőrző-ID, mind bekötve egy CLI QA skillbe. A verifikáció NEM böngészős — minden ellenőrzés a name_guard.py futtatása fixtúrákon, és állítás a visszakapott JSON-re / kilépőkódra.

Bemenet: az Instance 1 HANDOFF (gyökérok + döntések). Kimenet: végrehajtható checklist.md (piros→zöld), 2 architektúra-döntés (ADR), egy campaign-name-guard-qa skill ami bizonyítja a boxokat, és egy copy-paste prompt az Instance 3-nak.

Why this mattersA checklist minden boxa hordozza a gyökérokot (file:line), a konkrét változtatást, és egy állítást ami ELŐBB pirosan bukik, majd a javítás után zöld. Így az Instance 3 nem érvelésből pipál, hanem futó bizonyítékból — a baki nem térhet vissza észrevétlenül.

flowchart LR
  H["HANDOFF<br/>(Instance 1)"] --> P["Tech spec<br/>(Instance 2)"]
  P --> C["checklist.md<br/>A·B·C·D"]
  P --> A["2 ADR"]
  P --> Q["QA skill<br/>10 ID"]
  P --> X["PROMPT_to_execute"]
  X --> E["Instance 3<br/>épít + bizonyít"]

A · name_guard.py — az őr magja

TL;DRÚj szkript, ami a fit_classifier.py Gemini-hívásmintáját újrahasznosítja. Szemét-ellenőrzés = sima kód; ékezet + sorrend + kétesség = modell.

Bemenet: egy lead nyers Keresztnév/Vezetéknév. Kimenet: {first, last, salutation, ambiguous, status}. A1 ékezetet állít vissza, A2 'Tisztelt Budai Bálint!' megszólítást gyárt, A3 CSAK a valóban kétes sorrendet jelöli (Kazuhiro Tsuda átmegy!), A4 a szemetet (13000, üres) keményen elutasítja.

Why it mattersA determinisztikus/modell szétválasztás a kulcs: a szemétszűrés nem bízható a modellre (garantált kell legyen), de az ékezet/sorrend emberi ítéletet igényel — azt olcsón a Gemini adja, a maradék bizonytalanságot pedig emberhez küldi.

flowchart TD
  A["Nyers név"] --> B{"Szemét?<br/>(kód)"}
  B -->|igen| R["reject"]
  B -->|nem| G["Gemini:<br/>ékezet+sorrend"]
  G --> D{"Egyértelmű?"}
  D -->|igen| S["salutation kész"]
  D -->|nem| F["ambiguous=true<br/>→ ember"]

B · Feltöltési kapu (a szent emberi kapu)

TL;DRAz őr kötelező lépés feltöltés ELŐTT. Bármely kétes/reject lead → nem-nulla kilépés + BLOCK, az assemble a javított értéket használja.

Bemenet: a leadek CSV-je feltöltés előtt. Kimenet: kilépőkód 0 ha minden tiszta, ≠0 ha bármi kétes (megnevezve a sort). B2: az assemble_deliverable.py:82 naiv összefűzése helyett a javított, sorrend-helyes nevet írja.

Why it mattersEz teszi lehetetlenné a visszaesést: semmi nem jut az Instantlybe emberi jóváhagyás nélkül, ha kétes. Az emberi kaput nem gyengítjük — automatizáljuk a felismerést, nem a döntést.

flowchart LR
  C["leadek CSV"] --> G["name_guard<br/>(kapu)"]
  G -->|"0 kétes"| U["feltöltés OK"]
  G -->|">0 kétes"| B["BLOCK<br/>exit≠0 → ember"]

C · K-X élő javítás (92 lead)

TL;DRÉlő-státusz check → szünet → őr a 92 leaden → kétesek feloldva → {{salutation}} egyedi változó bevezetése → újratöltés → élő ellenőrzés.

Bemenet: a mostani hibás extended_tab.csv + az ÉLŐ kampány copy (amit Instance 3 először beolvas!). Kimenet: javított nevek + a 'Tisztelt {{first_name}}' lecserélve '{{salutation}}'-re, minden lead helyes megszólítással.

Why it mattersAz {{first_name}} helyben-írása helyett külön {{salutation}} változó (ADR-0002): a keresztnév megmarad más célra, a formális köszönés a saját mezőjében utazik. Az élő ellenőrzés kötelező — a 'sikeres' log nem bizonyíték (K-X incidens tanulsága).

flowchart LR
  S["live_status"] --> P["szünet"]
  P --> G["őr 92 leaden"]
  G --> R["kétesek<br/>feloldva"]
  R --> V["{{salutation}}<br/>változó"]
  V --> U["újratöltés"]
  U --> E["élő check"]

D · Skill + globális szabály

TL;DRDedikált GLOBÁLIS skill (campaign-name-guard) az őr köré, plusz hub CLAUDE.md invariáns: neveket ELLENŐRIZNI kell minden kampány előtt.

Bemenet: Matt kérése egy skillre + a globális szabályra. Kimenet: .claude/skills/campaign-name-guard/ ami a name_guard.py-t futtatja, a cold-email-pipeline mint kötelező elő-feltöltési lépés hivatkozza, és egy hub-szintű szabály ('checked', NEM 'mindig teljes név'; kétes → kérdezd az embert).

Why it mattersGlobális, mert minden kliensnél újrahasznosítható. A szabály szándékosan 'ellenőrizve', nem 'mindig teljes név' — a rugalmasság megmarad, de az ellenőrzés kötelező lesz.

flowchart TD
  SK["campaign-name-guard<br/>skill (globális)"] --> NG["name_guard.py"]
  PL["cold-email-pipeline"] -->|"kötelező elő-lépés"| SK
  CM["hub CLAUDE.md"] --> RULE["invariáns:<br/>nevek ellenőrizve"]

★ Kulcsdöntések (ADR-ek)

TL;DRADR-0001: Gemini-őr determinisztikus elő-ellenőrzéssel. ADR-0002: számított {{salutation}} egyedi változó.

Bemenet: a HANDOFF nyitott kérdései (D1-D3). Kimenet: mind lezárva — nincs nyitott kérdés a végrehajtás előtt. Modell: Gemini 2.5 Flash-Lite, meglévő GEMINI_API_KEY, új titok nélkül.

Why it mattersA jövőbeli karbantartó ebből érti meg, MIÉRT nem tiszta kóddal döntjük el a sorrendet (emberi ítélet kell), és miért külön mezőben a köszönés (a first_name megmarad). A taktikai választások a HANDOFF-ban maradnak, csak ez a kettő ADR.

flowchart LR
  D1["D1: salutation"] --> A2["ADR-0002"]
  D2["D2: dedikált skill"] --> OK["globális"]
  D3["D3: kétesség"] --> A1["ADR-0001"]