Lead Grader

lead-grader

What this is (and isn't)

A runnable tool at tools/lead-grader/ — real Python code with tests, not instruction-only prose. This skill is the conversational front door to it: when a member asks in natural language, drive the CLI on their behalf and report back in plain English.

v1 grades CallRail calls only. It is not (yet) an LSA scorer, a form-fill triager, or an outbound-prospect tiering tool — those are named "Later phase" in README.md and not built. If the member asks for one of those, say so plainly and point at the README's "Later phase" section rather than improvising a partial version.

It does not auto-send anything, auto-dispute anything with Google, or write back to any CRM — it reads and grades, and hands the member a digest to act on themselves.

When this runs

• "Grade my calls for [client]" / "run my lead grader" / "how were today's leads" -> the daily one-command pipeline.
• "Build a rubric for [client]" / "teach the grader what a good lead looks like" -> the rubric wizard (first-time setup, or when the client's ideal-customer definition changes).
• "Is [client]'s lead quality getting worse" -> the trend view.
• "Set up lead grading for a new client" -> the one-time client setup (copy clients/_example/, fill in config.yaml, then run the wizard).

How to run

All commands run from tools/lead-grader/. First-time setup per README: .env filled in (CallRail + one LLM key), clients/<slug>/config.yaml created from clients/_example/.

One-time per client — build the rubric:

python3 run.py --client acme wizard

This is an interview — collect 5-10 real example calls with the grade the member would give each one and (optionally) why, in the chat itself, then drive the wizard's prompts with those answers. Show the draft rubric before it's saved; the wizard asks for a save confirmation itself.

Daily habit — one command:

python3 run.py --client acme

Import + grade + digest, using sane defaults (yesterday's calls). Read the printed digest back to the member in plain English — lead-by-lead if there are only a few, or just the summary line and the 🔥 Hot ones if there are many. Mention the HTML file path it wrote.

Finer control, when asked:

python3 run.py --client acme import --days 7   # wider pull
python3 run.py --client acme grade              # (re)grade only
python3 run.py --client acme digest --send      # also push to Slack/email
python3 run.py --client acme trend --days 7      # quality trend

New client setup:

cp -r clients/_example clients/<slug>

then help fill in config.yaml (client name, CallRail company id, optional digest destination) before running the wizard.

Output

• Terminal digest — one line per lead, sorted Hot-first, grade emoji
  • one-line reason + the key quote when there is one; a summary line at the top ("Graded N leads for X — Y hot, Z qualified, ...").
• HTML file at output/digest-<client>-<date>.html — same content, readable/shareable without a terminal.
• Trend output — per-day grade counts and junk rate for the window asked for.
• Every command exits non-zero with a plain-English message on a real failure (missing client config, no rubric yet, no LLM key) — relay that message to the member rather than guessing at the fix yourself.

Common mistakes

• Don't skip the rubric step. grade refuses to run without clients/<slug>/rubric.md existing — that's intentional, not a bug to route around. Run the wizard first.
• Don't fabricate a digest from memory. If grade/digest reports zero leads or zero grades, say so — don't invent example output to look helpful.
• Don't promise LSA, form-fill, or CRM-push behavior. They're listed under "Later phase" in the README precisely because they aren't built; offering them as if they work would be the kind of overselling the whole Founding Circle tool family is built to avoid.
• A "Weak / needs human review" grade is a feature, not a bug — it means the grading engine couldn't parse a clean verdict and chose not to guess. Don't reinterpret it as an error to fix; tell the member it means "look at this one yourself."
• Never commit a real client's clients/<slug>/ folder — it's gitignored on purpose (client names, rubrics, webhook URLs). Only clients/_example/ belongs in this public repo.