# Grifter Filter — Product Requirements Document

**Version 0.2 · July 2026 · Status: shipped MVP (P0 + P1)**

---

## 1. Vision

> **Rank resumes by fit — and by whether the claims survive contact with the candidate's actual GitHub.**

Every resume screener scores *relevance*. Almost none score *truth*. Grifter Filter treats a resume as a set of factual claims, retrieves evidence from the candidate's public GitHub, and issues a FEVER-style verdict per claim — `SUPPORTED`, `REFUTED`, or `NOT_ENOUGH_INFO` — with a citation the reviewer can click. Fit, truthfulness, and authenticity are scored separately, because collapsing them into one number hides exactly the information a hiring manager needs.

## 2. The problem (why this matters)

- **44% of US job seekers admit lying during hiring**, and 24% falsified the resume itself (Resume Builder, Jan 2025). Only ~26% of embellishments are ever caught.
- **GitHub portfolios are gameable at scale**: a CMU study ("StarScout", arXiv:2412.13459) found **6M+ fake stars** across 18,600 repos; commit histories are trivially backdated with `GIT_AUTHOR_DATE`; forked tutorials get presented as original work.
- **Recruiters distrust AI screeners for a specific reason**: the #1 documented complaint (2025–26) is *"a high match score with no reasoning, so I read the resume anyway."* An opaque score saves nobody any time.

The opportunity: a screener whose every output is **evidence-linked and honest about uncertainty** is both more useful and more defensible than a black-box score.

## 3. Personas

| Persona | Need | What they get |
|---|---|---|
| **Startup founder / eng hiring manager** (primary) | Screen 100+ applicants without an ATS or a recruiting team | Ranked table, fraud flags, one-click evidence, PDF to forward |
| **Technical recruiter** | Artifacts to hand the interview panel; defensible shortlists | Per-candidate PDF report, targeted interview questions, audit log |
| **Candidate** (fairness stakeholder) | Not being auto-rejected by a black box | NEI-honest verdicts, no auto-reject rule, blind-screening mode, human-override record |

## 4. Product principles

1. **Never bluff.** If public evidence can't prove or disprove a claim, the verdict is `NOT_ENOUGH_INFO` — the honest default, not a failure mode.
2. **Every verdict cites its evidence.** A claim without a clickable source is an opinion, and we don't ship opinions.
3. **Signals are questions, not accusations.** Fraud signals link to the GitHub page where a human can check; the interview-question generator turns each into a fair, answerable prompt.
4. **Decision support, never decisions.** No auto-reject exists in the product. The disclaimer is always visible; the human's override note is recorded.
5. **Degrade gracefully, stay free.** No Tinker key → deterministic heuristics. No GitHub token → shallow mode. The public demo never hard-fails.

## 5. Features

### P0 — core (shipped)
- Multi-PDF resume upload + JD input; regex/heuristic field parsing (name, email, GitHub, CGPA, skills, projects, experience, claimed years).
- GitHub evidence retrieval (repos, languages, commits, contributors, READMEs) with 15-min cache and rate-limit-aware shallow/deep modes.
- LLM claim extraction and claim judging via **Tinker** (OpenAI-compatible endpoint, default `openai/gpt-oss-20b`), with strict evidence-only judging rules and full heuristic fallback.
- Three separated scores (JD-fit / Verification / Authenticity) + weighted final; user-adjustable weights.
- Ranked table, CSV/JSON export, per-candidate detail with per-claim evidence expanders.

### P1 — differentiators (shipped)
- **Fraud-signal engine (7 signals)** — see catalog below.
- **Evidence deep-links** on every verdict and signal (`LinkColumn`, `link_button`, URLs in PDF).
- **JD Requirements Matrix** — the JD is decomposed into atomic must-have/nice-to-have requirements; each candidate is graded met/partial/none per requirement with evidence links (refuted claims veto "met"). This mirrors how hiring managers actually evaluate.
- **Targeted interview questions** generated from REFUTED/NEI claims and fraud signals — converts distrust into a concrete next step, each with a "listen for" rubric.
- **Per-candidate PDF report** (fpdf2) — the artifact that actually gets forwarded to panels.
- **Side-by-side comparison page** (2–4 candidates) with per-metric winner highlighting.
- **Shortlist/status tagging** — inline in the ranking table (editable status column) and per-candidate, plus reviewer override note, recorded in the audit log.
- **Blind-screening mode** — redacts name/email/GitHub handle/CGPA/education lines from LLM prompts, all views, **and all exports** (CSV/JSON/PDF/audit).
- **Sample-data demo mode** — one-click fictional screening (strong / inflated / no-GitHub archetypes), zero API calls.
- **Methodology page** — every formula and threshold published in-app.
- **Audit-log JSON export** — model, weights, verdicts, signals, timestamps, disclaimer.
- **Parallel GitHub prefetch** — snapshots fetched concurrently before the LLM loop (~2× faster batches).

### P2 — documented future (not built)
ATS write-back (Greenhouse/Lever/iCIMS), reference-check cross-validation, private-repo OAuth reconciliation, MOSS-style code-plagiarism detection, coder-percentile benchmarking, labeled eval benchmark with published precision/recall, independent bias audit + four-fifths dashboard, notice/consent + retention/erasure workflows, session restore from exported JSON, multi-JD presets, advance-only email drafts.

## 6. Fraud-signal catalog

| Signal | Data source | Trigger | Severity |
|---|---|---|---|
| Low contributor share | `/repos/{r}/contributors` | Candidate <25% of contributions on own repo (≥5 total) | high |
| Commit clustering | `/repos/{r}/stats/commit_activity` | ≥80% of a year's commits in ≤2 weeks, repo >6 months old | high |
| Commit clustering (fallback) | sampled commit dates | ≥5 recent commits within 2 days on an old repo | warn |
| Identity mismatch | commit author fields | >50% of sampled commits by other logins/emails | high |
| Mostly forks | repo list | >50% of recent repos are forks | warn |
| Star anomaly | stars vs subscribers | ≥40 stars, watcher/star <0.5% (StarScout pattern) | warn |
| Language not found | `/repos/{r}/languages` | Claimed language, zero bytes anywhere | warn |
| Account age gap | user `created_at` | Claimed experience > account age + 1yr | warn |
| AI-assistance markers | root files, commit trailers | `.claude/`, `.cursor/`, AI co-author trailers | info — *explicitly not fraud* |

## 7. Success metrics

- **100% of non-NEI verdicts carry a clickable evidence link** (product invariant).
- Full 5-resume analysis completes in **< 3 minutes** on the free tier.
- LLM cost **< $0.01 per candidate** (measured: ~9 calls ≈ $0.002 on gpt-oss-20b).
- Demo credibility test: a planted fake claim ("1M orders/sec Rust engine" on a Python-only profile) is REFUTED or flagged — verified in E2E.
- Zero hard failures with no API keys configured (fallback invariant).

## 8. Compliance posture

This is a **portfolio/demo tool**, deliberately built inside the guardrails that real deployments require:

- **No automated rejection** — GDPR Art. 22's "solely automated decision" line is never crossed; a human override field exists and is logged.
- **Transparency** — scoring formulas and thresholds are published in-app (Methodology page), the direction NYC Local Law 144 and the EU AI Act (Annex III classifies CV-screening as high-risk) push toward.
- **Bias mitigation** — blind-screening mode responds directly to the 2024 UW study (LLM screeners favored white-associated names in 85% of trials); evidence-required verdicts limit name-driven halo effects.
- **Accountability** — per-run audit log (model, weights, verdicts, overrides, timestamps).

**Before any production hiring use**, an operator would additionally need: an independent bias audit with published results (NYC LL144), candidate notice/consent (Illinois AIVIA / NYC), an adverse-impact dashboard (EEOC four-fifths), data-retention and erasure controls (GDPR), and a validation study (EEOC business-necessity defense). These are documented, not built.

## 9. Rollout

| Phase | Contents | Status |
|---|---|---|
| 0 | Security fix, correct Tinker integration (OAI-compatible endpoint), dependency slim-down | ✅ |
| 1 | PRD + Architecture docs, HF Spaces deployment | ✅ (docs) / deploy step |
| 2 | Fraud engine, evidence deep-links, top-K judging | ✅ |
| 3 | Interview questions, PDF reports, compare view, shortlist | ✅ |
| 4 | Blind mode, methodology page, audit log, disclaimers | ✅ |
| 5 (next) | Labeled eval benchmark (~100 claims) with published precision/recall; sample-resume gallery | — |