screen-alerts

Screen Alerts

You are running the job alert screening pipeline (PRD: docs/PRD-job-alert-pipeline.md). Work from the repo root (the directory containing this plugin). Be quietly mechanical: this runs unattended. Never ask the user questions; degrade gracefully and record problems in the run report instead.

Architecture (how this skill is invoked)

bin/run-pipeline.sh splits this pipeline into three phases so the slow, mechanical resolve step never sits inside an LLM turn (the agent twice backgrounded it and abandoned the batch, 2026-06-11 and 2026-06-13):

• Ingest (agent): Phase 0-1 only. Gmail search and parse, writing parsed jobs to a temp file. Invoked with a scoped prompt.
• Resolve (deterministic bash): scripts/pipeline-mechanical.sh runs dedup, ledger upsert, and resolution to a temp resolved.json. No agent.
• Score (agent): Phase 4 onward. Reads resolved.json and does the judgment work: scoring, report, ledger updates, apply queue, CV drafts.

When invoked for scoring, resolution is already done: read the resolved file, do NOT re-ingest or re-resolve. The phase docs below remain the reference for what each step must accomplish. If this skill is ever run end-to-end in one turn, never background a command: run everything synchronously (rule 8).

Hard rules (from the PRD)

1. NEVER fetch LinkedIn URLs. The email is a lead source only.
2. Freshness comes from the canonical source's posted date, never from email metadata or aggregator claims.
3. Unverifiable jobs are labeled and ranked below verified ones, never silently dropped.
4. Every reported job carries a citation: where found, how verified.
5. No em dashes in any generated text. Use colons, periods, or commas.
6. Never invent experience in CV content; every claim must trace to the master CV or career brief.
7. If a stage fails outright (Gmail unreachable, brief missing), write a run report that says so plainly and stop. A partial report that looks complete is worse than an honest failure report.
8. Run every step SYNCHRONOUSLY in the foreground. Never use background execution for any command and never end your turn before Phase 7 is complete: in headless mode there is no next turn, and ending early kills in-flight work (this exact failure happened on 2026-06-11: the resolver was backgrounded, the turn ended, and 288 jobs were left unscored). Slow commands are fine; wait for them.
9. If the report file for today already exists, do not overwrite it; append a -run2 (-run3, ...) suffix to the filename and use that name in all links.

Phase 0: Config and preflight

1. Read data/pipeline.local.json (fall back to data/pipeline.example.json only to learn the shape; a missing local config is a failure, see rule 7).
2. Read the career brief at career_brief_path. If its mtime is older than brief_stale_days, add a STALE BRIEF warning to the report header. Also read brief_overrides_path if it exists: private exclusions and preferences that carry the same authority as the brief and win where they conflict. The overrides file is local-only; never copy its contents into committed files, and cite it in reports only as "private exclusion: ". Also read experience_bank_path if it exists: the candidate's full career history (including jobs too old or minor for the printed CV) plus academic CV. It is confirmed-true source material. Use it in scoring (credit experience the 2-page CV omits) and in CV tailoring (draw real details from it when rewriting editable sections, especially earlier-career; surface a role-relevant old job in the candidate's true words). Never invent beyond what it states; never copy it into committed files.
3. Check master_cv_path mtime against the generated_from_mtime field in story_map_path. If the map is missing or stale, regenerate: python3 scripts/idml-story-map.py --cv <master_cv_path> --out <story_map_path> and flag the new map for confirmation in the report.
4. Start a stats object: started, emails_reviewed, jobs_extracted, jobs_verified, jobs_deduped, jobs_skipped, tier1_count, cvs_generated.

Phase 1: Ingest from Gmail

1. Load Gmail tools with ToolSearch (query "gmail"). If unavailable, fail per rule 7.
2. For each sender in gmail_senders: search threads with from:<sender> newer_than:<gmail_lookback_days>d, paging until exhausted (pageSize 50).
3. For each thread, get_thread with FULL_CONTENT. Results usually exceed the inline limit and are saved to a file; either way, extract .messages[].plaintextBody with jq into a temp file and run: python3 scripts/parse-alert-email.py --text < body.txt Collect all parsed jobs into one array. Count emails_reviewed and jobs_extracted.

Phase 2: Ledger dedup

1. Within-batch dedup: python3 scripts/deduplicate-jobs.py.
2. Ledger: python3 scripts/ledger.py upsert (reads/writes the job array).
3. Keep only jobs with ledger_status == "new". Jobs previously seen are not re-reported; count them as deduped.
4. python3 scripts/ledger.py expire --days <ledger_expire_days> to age out stale rows.

Phase 3: Resolve to canonical source

1. python3 scripts/resolve-job.py annotates each job with source_type "ats" (canonical URL + real posted date) or "unverified".

2. For each still-unverified job, try the free APIs with company or title keywords: scripts/search-remotive.sh, search-themuse.sh, search-jobicy.sh, search-himalayas.sh, search-remoteok.sh, piping through normalize-jobs.py --source <api>. Fuzzy-match titles (same spirit as resolve-job.py). On a match: source_type "api", take the API's URL and posted date, verification_status API_ACTIVE.

3. Last resort, only for roles that would plausibly score Tier 1 or 2: one WebSearch per job for "<title>" "<company>" careers OR jobs, looking for the employer's own careers page or ATS posting. If found, run scripts/verify-url.sh <url>: VERIFIED -> source_type "web"; EXPIRED -> mark skipped with reason; otherwise source_type stays "unverified".

4. Manual evidence folder (done in the SCORE phase, since reading PDFs needs the model): read any PDFs directly in data/job-ads/ (ignore the processed/ subfolder). For each, extract company, title, work mode, posted date, and description from the ad, then match to a ledger row (same fuzzy company+title spirit as resolve-job.py; check both this batch and existing rows via ledger.py check). On a match: treat the ad as the job's full text for scoring, set source_type "manual", verification_status MANUAL_EVIDENCE, and use any posted date from the ad for freshness. The user supplied the ad deliberately, so a manual- evidence job skips the unverified penalty, but it is still labeled "manual evidence (user-supplied ad)" in the report with the citation. If a PDF matches no known job, score it as a new lead anyway and note where it came from. After processing, move the file into data/job-ads/processed/.

   Precedence when the matched job already has a disposition (a duplicate drop is a user mistake to absorb, not an override):

   • Already verified (source_type ats/api/web): keep the stronger verification; use the ad only to fill missing description or work mode. Report note: "ad supplied; already verified via ".
   • Status applied: do nothing; note "ad supplied for a role already applied to".
   • Status skipped: do NOT re-score or resurrect. Note "ad supplied for a role previously skipped (); ask me to reconsider it if that was intentional". An explicit user request in a session is the only path back from skipped.
   • Status reported but unverified: the intended case; upgrade to manual evidence and re-score. In every case the PDF is moved to data/job-ads/processed/ so it is consumed once.

5. Freshness rule: jobs whose canonical posted_date is older than freshness_days are skipped with reason "stale (posted )". Jobs with no canonical date stay unverified: labeled, ranked below verified jobs, never dropped. Manual-evidence jobs without a date in the ad count as fresh: the user just printed them.

Phase 4: Score against the career brief

Use the Phase 6 rubric from the match-jobs skill, unchanged: skills 0-30, seniority 0-20, sector 0-20, work mode 0-15, culture/values 0-10, recency 0-5. Tiers: 80-100 Tier 1 (strong), 60-79 Tier 2 (good), 40-59 Tier 3 (growth).

Score on the full job description, not the title. Each resolved job carries description_text (the resolver fetches the complete ad: Greenhouse via content=true, Workday via its detail endpoint, Ashby/Lever/Workable from the listing). Read it and score skills, sector, culture, and the product-mandate guard against what the ad actually says. A job flagged thin_description: true (under 200 characters resolved) could not have its full ad fetched: score it conservatively on title and metadata, and say so in the report ("scored on title only, full ad not retrievable"). Do not let a thin description silently depress a verified role without noting why.

Apply, in this order:

1. Private overrides first: exclusions from brief_overrides_path are dealbreakers; quiet preferences adjust scores. In reports, cite only "private exclusion: ".
2. Dealbreakers from the brief (score 0, skipped with reason): rigid office mandates (5 days in office, mandatory relocation), requirements factory cultures, IC-only roles without ownership, innovation theater, pure research without product mandate, sales/quota roles, deep engineering build roles, PMO/reporting roles.
3. Citizenship eligibility (hard skip, score 0): the user is a US citizen, not a Gulf-state national. Skip any role restricted to nationals of a country she does not hold, with reason "ineligible: ". Catch title and description signals such as "Emirati only", "UAE Nationals only", "Emiratization", "Saudi Nationals only", "Saudization", "GCC nationals only", "Qatari/Bahraini nationals only", "open to nationals only", "reserved for citizens". This is an eligibility bar no visa sponsorship overcomes, and it is separate from (and overrides) the Gulf in-office preference. Note: a role about researching or supporting nationalization (e.g. the user's own past Emiratization design work) is NOT restricted; only skip roles that restrict the applicant's nationality. For unverified roles, only the title is visible, so a restriction stated only in the body cannot be caught until the role is verified; do not assume a Gulf role is open just because the title is silent.
4. Standing location rules:
   • Dubai/UAE roles: assume visa sponsorship unless the posting says otherwise; do not penalize missing visa language.
   • US remote roles: viable (US citizen). "Must reside in US" plus remote is viable.
   • Singapore: acceptable, no penalty.
5. Product-mandate guard (the keyword-bait check): if a role scores high mostly on methods keywords (foresight, workshops, storytelling, design thinking, HCD), check what the role produces and who owns the output. If outputs are reports feeding someone else's plan, with no build or ship mandate, cap the score at 59 (Tier 3) and record the reason. Methods vocabulary reliably over-attracts; this guard exists because of it.
6. Unverified penalty: unverified jobs get recency 0 and are listed in a separate, clearly labeled section, after verified jobs, regardless of score.

For every scored job, update the ledger: python3 scripts/ledger.py set-status --key <ledger_key> --status reported --score N --tier N --canonical-url URL --source-type TYPE --posted-date DATE --location "<city/country>" --work-mode <remote|hybrid|onsite> (location and work-mode come from the resolved job; they surface in the apply queue.) (or --status skipped --note "<reason>" for dealbreakers/stale).

Phase 5: Report and vault delivery

1. Write the run report to <reports_dir>/YYYY-MM-DD-job-screen.md and copy it to <vault_reports_dir>/ (create directories as needed).
2. Report structure:
   • Header: date, stats line, any warnings (stale brief, new story map, failed sources).
   • Tier 1 and Tier 2 sections: for each job, score breakdown by dimension, a two line rationale, canonical link, verification status, source citation, posted date.
   • Unverified section (if any): same format, clearly labeled "could not verify against a canonical source".
   • Collapsed summary (details/summary block) of skipped jobs with one line reasons: stale, dealbreaker, duplicate, expired.
3. Regenerate the apply queue deterministically: python3 scripts/render-apply-queue.py. It reads Tier 1 reported rows from the ledger and writes <vault_apply_queue> in the exact ## {Title}: {Company} format the Recall daily note parses. Do NOT hand-write the queue; the script owns its format. When the user marks a role applied or skipped, update the ledger with ledger.py set-status and re-run the renderer.
4. Vault writes are additive only: never modify other files in the vault.

Phase 6: CV drafts for Tier 1 (human-gated)

Only for tiers in cv_tiers (default: Tier 1 only). Drafts only; never submit anything.

1. Read the story map (story_map_path) and the master CV. Editable stories and their roles come from the map; never touch stories outside the whitelist.

2. Edit for the role's vibe, not just keywords. Before writing anything, read the full ad and write yourself a short register map: its vocabulary (the actual nouns it uses for people, work, and outcomes), its themes, what it values, its tone. A museum's register is audience, visitors, cultural sensitivity, public engagement, accessibility; a fintech's is customers, risk, compliance, scale. Then rewrite the candidate's TRUE experience to speak in that register. Tailoring is editorial, not literal: the timid failure mode (observed 2026-06-13) is hugging the master CV's wording and changing almost nothing.

   Concretely, across profile, core strengths, methods/tools, AND the most role-relevant experience bullets (the page 3 letter gets the v1 placeholder, not a tailored letter), do all of:

   • Swap terminology to the role's register ("customer" -> "audience" or "visitor" for a cultural role).
   • Add true keywords the ad asks for, even if the master CV omits the exact words. The bar is TRUTH, not "verbatim in the master CV": if the candidate genuinely does the thing (per the brief, the master CV's implications, or confirmed by the user), name it in the ad's words (e.g. data visualization, Google Analytics, emerging-technology research, digital accessibility, content standards). Never claim experience the candidate does not have.
   • Drop irrelevant items. Cut strengths and methods/tools the role does not care about ("Zero-to-One Product Strategy" on a heritage role, dev tools like Jira/Confluence on a non-engineering role) rather than only reordering. Shrinking is layout-safe (just white space); the tool allows a run down to 40% of its original length.
   • Rewrite 4-6 experience bullets to say the same true thing in the ad's vocabulary, and reorder to lead with the most relevant. idml-apply replaces existing runs but cannot ADD a bullet, so to surface a role-critical theme (e.g. budget/team management) reword the least-relevant existing bullet into it.

   Content rules: every claim is TRUE (traceable to the master CV, the career brief, or the candidate's confirmed experience), expressed in the role's language; British or American spelling follows the posting; tone matches the master CV; no em dashes. Growth budget: framing lines +cv_length_budget_pct% (default 10); experience bullets up to +20% (pass --budget-pct 20), since the ad's vocabulary sometimes needs the room.

3. Apply: python3 scripts/idml-apply.py --cv <master_cv_path> --map <story_map_path> --edits <edits.json> --out <cv_drafts_dir>/CV-rabourn-<company-slug>-<YYYY-MM-DD>.idml The script enforces the whitelist, length budget, XML well-formedness, and IDML packaging rules; treat its failure as a per-job failure, note it in the report, and continue with other jobs.

4. Write a plain text diff summary next to each draft (same name, .changes.txt): what changed, why, and a reminder to check for overset text in InDesign.

5. Write a job-ad companion file next to each draft, named CV-rabourn-<company-slug>-<date>.job-ad.md, with TWO clearly separated, clearly labelled parts:

   • "## Matched keywords (pipeline analysis)" that YOU write: the terms from the ad that map to Tanya's real skills/experience, each as "<ad term>" -> <where it is true in her background> (drawing on the brief, master CV, and experience bank). Follow it with a short "### Not claimed / gaps" list of notable ad requirements she does not meet, so the picture is honest.
   • "## Job ad (verbatim)" containing the captured ad text exactly as received (description_text, or the manual-evidence PDF text), with its source URL/file and capture date. Do not edit or summarize this part. A horizontal rule and the headers must make it obvious which part is the pipeline's analysis and which is the untouched ad.

6. Update the ledger with --cv-path and add the draft to the apply queue entry.

Phase 7: Run log

1. Finish the stats object (finished, outcome "ok" or "failed: ") and record it: python3 scripts/ledger.py log-run (JSON on stdin).
2. Append one line to logs/pipeline.log: <ISO date> | emails N | extracted N | new N | verified N | tier1 N | cvs N | <outcome>.