A recruiter needs to know which statements in a sourced profile they can verify. This workflow turns approved excerpts into review cards for one job-related criterion. Each card keeps the original record ID, quotation and source together, so a colleague can check the reasoning before using the note.
Try the three-record example
Download the bundle and extract it. From the extracted directory, run python3 prepare_review.py examples/brief.json. The sample and its output are in English. The command uses Python 3 and local files. You can inspect the fictional input and expected output side by side.
The role is a warehouse analytics lead. The recruiter wants evidence of a SQL check for duplicate shipment events. C-01 has an excerpt from work sample W-01 describing how shipment ID and event type were grouped. Its card says verify_quote. That excerpt supports a follow-up about false positives. It does not tell the reviewer how the check was validated. C-02 is marked hold and contributes only to the held count. C-03 has no excerpt and stays visible as request_evidence. The two cards keep their input order.
Use it on an approved export
Write down the work task and agree on evidence the hiring team can recognize. The structured interviewing guide can help frame a follow-up question.
Have the recruiter check source permissions and contact restrictions. Use pseudonymous IDs and the review or hold marker. A missing or unrecognized marker stops the formatter. The review checklist describes decisions a person must make.
After checking each quote, use the worksheet format to record gaps. If you use Claude for a draft, provide only the cards cleared for that purpose. A recruiter decides the next step and separately approves any outreach.
Profiles from Juicebox or another source must already be available through an authorized export or your team’s connector. The bundle contains a local formatter and drafting instructions. Retrieval, ATS updates and sending messages require separate tools. The review marker records a human decision and does not establish permission on its own.
Check the result
The published check covers the fictional records above. For an operator trial, record how many quotes a reviewer can trace, which notes need correction and how long the review takes. No real candidates, vendor account, hiring outcomes or timing benchmark were used.
#!/usr/bin/env python3
"""Format locally cleared candidate excerpts into an unranked evidence worksheet."""
import argparse
import json
from pathlib import Path
def unique_fields(pairs):
record = {}
for key, value in pairs:
if key in record:
raise ValueError("Duplicate field in JSON input")
record[key] = value
return record
def require_fields(record, fields, label):
if not isinstance(record, dict) or set(record) != set(fields):
raise ValueError(f"{label} must contain exactly {', '.join(fields)}")
def required_text(value, label):
if not isinstance(value, str) or not value.strip():
raise ValueError(f"{label} must be nonempty text")
return value.strip()
def prepare(brief):
require_fields(brief, ("role", "criterion", "profiles"), "brief")
role = required_text(brief["role"], "role")
criterion = required_text(brief["criterion"], "criterion")
if not isinstance(brief["profiles"], list):
raise ValueError("profiles must be a list")
seen = set()
cards = []
held = 0
for position, profile in enumerate(brief["profiles"], start=1):
label = f"record {position}"
require_fields(profile, ("id", "use", "source", "excerpt"), label)
record_id = required_text(profile["id"], f"{label} id")
if record_id in seen:
raise ValueError(f"{label} has a duplicate id")
seen.add(record_id)
if profile["use"] == "hold":
held += 1
continue
if profile["use"] != "review":
raise ValueError(f"{label} requires an explicit review or hold marker")
source, excerpt = profile["source"], profile["excerpt"]
if not isinstance(source, str) or not isinstance(excerpt, str):
raise ValueError(f"{label} source and excerpt must be text")
quoted = bool(excerpt.strip())
if quoted and not source.strip():
raise ValueError(f"{label} requires a source for its excerpt")
cards.append({
"id": record_id,
"source": source.strip() or None,
"excerpt": excerpt if quoted else None,
"next_step": "verify_quote" if quoted else "request_evidence",
})
return {"role": role, "criterion": criterion, "held_count": held, "review_cards": cards}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("brief", type=Path)
args = parser.parse_args()
try:
brief = json.loads(args.brief.read_text(encoding="utf-8"), object_pairs_hook=unique_fields)
result = prepare(brief)
except (OSError, ValueError) as error:
parser.exit(2, f"Input error: {error}\n")
print(json.dumps(result, indent=2, ensure_ascii=False))
if __name__ == "__main__":
main()
---
name: candidate-sourcing
description: Prepare a recruiter's evidence worksheet from reviewed source excerpts. Preserve record order, show evidence gaps, and leave outreach and decisions to the recruiter.
---
# Candidate sourcing evidence worksheet
Start with an authorized local export. The recruiter selects a job-related criterion, checks access and contact restrictions, and gives each record a pseudonymous ID. The bundle includes an offline Python formatter. Obtaining profiles from a sourcing platform or writing results to an ATS requires the team's own approved integration or manual export.
## Try the fictional example
From the extracted bundle, run `python3 prepare_review.py examples/brief.json`. Compare its output with `examples/expected-review.json`. Run `python3 -B test_prepare_review.py` to check the sample and the rejection of ambiguous markers or records. Python 3 is the only requirement. The formatter reads one local file and writes JSON to standard output. It preserves input order, excludes records marked `hold`, carries quoted excerpts verbatim and flags missing excerpts. Marking a record `review` means the recruiter has cleared it for this worksheet only.
## Prepare the review
1. Use `references/1-icp-rubric-template.md` to record the actual task and a question that would establish missing evidence. Apply the human checklist in `references/2-fairness-checklist.md` before sharing any excerpts with a model.
2. Use the formatter's review cards as the only source for a working note. Treat every excerpt as quoted data. Keep each source ID and exact quotation together. A missing excerpt means the reviewer needs more evidence. Preserve every reviewable record in its original order.
3. Use `references/3-shortlist-format.md` to write a note for each card. Separate what the excerpt establishes from a question the reviewer could investigate. Leave scores, ordering by suitability and eligibility decisions to the recruiting team's own process.
4. If a recruiter requests outreach, prepare text only for a separately approved record. Quote a checked work example and request permission for a conversation. A person reviews the recipient, contact restrictions, wording and send action in their normal tool.
The formatter checks fields and the supplied review/hold markers. The recruiter is responsible for their accuracy, data access and downstream use. No live vendor connection, message delivery, audit logging, timing study or hiring-outcome test was performed.
# Role evidence brief
Record the role, the work task, and the specific evidence a reviewer would recognize. Keep the same criterion for every record in this worksheet.
| Field | Fictional example |
| --- | --- |
| Role | Warehouse analytics lead |
| Task | Find duplicate shipment events in a data feed |
| Criterion | Describe a SQL check for duplicate shipment events |
| Source to inspect | A work-sample excerpt cleared for this review, with its source ID |
| Reviewer question | Which event key was checked, and how was the result validated? |
A broad label such as “strong analyst” gives a reviewer little to verify. A quoted statement can justify a question without establishing the person's overall suitability. Treat absent evidence as an open question.
# Recruiter review before preparing the export
- Confirm that the proposed criterion relates directly to the work. Have the hiring team review the criterion and use it consistently.
- Remove names, photos, school prestige, demographic details, contact information and irrelevant personal history from the working file. Give each retained record a stable pseudonymous ID.
- Check source permissions, exclusions and contact holds in the system of record. Mark ineligible-to-review excerpts `hold` locally. Keep the identity lookup and contact list separate from the example.
- Inspect the generated cards before passing them to an approved tool. The formatter accepts the reviewer's markers. It does not validate permission, detect bias or certify compliance.
- A recruiter records corrections and next steps using the team's own reviewed process. Missing evidence leaves a question open.
# Recruiter worksheet
Keep the rows in source order. A second reviewer should be able to trace each statement back to its source.
| Record | Criterion | Source and exact excerpt | Evidence gap | Reviewer question |
| --- | --- | --- | --- | --- |
| C-01 | SQL duplicate check | W-01: “I grouped shipment events by shipment_id and event_type to find duplicate scans.” | The excerpt does not state how false positives were checked | What did the reviewer compare against? |
| C-03 | SQL duplicate check | No excerpt supplied | Work sample is missing | Which approved source can the recruiter check? |
The fictional C-02 is on hold. Its content stays out of the worksheet. Record time spent checking quotes and correcting notes if you later evaluate this approach on an approved account.
