stathead: Command for Claude Code

You are running the prospect-guide feature extraction pipeline. This command processes PDF text caches written by scripts/extract_pdf_features.py and turns each guide into structured per-player JSON.

Optional filename filter

The invocation may include an argument string: $ARGUMENTS

• If $ARGUMENTS is empty / whitespace, process every PDF as normal.
• Otherwise treat it as a case-insensitive substring. Only process text caches whose stem (the filename without .text.txt) contains this substring. Skip everything else without touching their caches.

Examples: /extract-pdf-features rookie_scouting → only RSP guides. /extract-pdf-features 2025 → only 2025-dated PDFs. /extract-pdf-features → all of them.

Report to the user up-front: "Filter: (N of M PDFs match)" or "Filter: none (processing all N PDFs)".

Step 1: make sure text caches exist

Run python3 scripts/extract_pdf_features.py via Bash. It decrypts every PDF in pdfs/ and writes pdfs/.cache/*.text.txt. If it errors (missing deps, no PDFs, bad password), surface the error to the user and stop.

Step 1.5: load optional extraction context

If pdfs/.extraction-context.md exists and is non-empty, read it. Compute its short SHA-256 hash via Bash:

shasum -a 256 pdfs/.extraction-context.md | cut -c1-8

Hold onto two values for the rest of this run:

• CONTEXT_TEXT: the file's contents (may be empty if the file doesn't exist)
• CONTEXT_HASH: the 8-char hash, or the literal string nocontext if the file is missing/empty

The context lets the user inject domain-specific guidance (e.g. "Beast tiers go 1-5, not 1-3"; "treat 'Edge' positions as DL even if listed as LB") without editing this slash command. Including the hash in cache filenames (next step) ensures editing the file invalidates stale features.

Step 2: process each text cache

Use Glob to list pdfs/.cache/*.text.txt. For each text file:

• Compute the corresponding features path: pdfs/.cache/<stem>.<CONTEXT_HASH>.features.json where <stem> is the filename without .text.txt and <CONTEXT_HASH> is from step 1.5.
• If that features file already exists, skip this PDF (it's already been processed with the current context). Tell the user "skip : cached".
• Otherwise:
  1. Read the text file in full (it may be large; chunk via the Read tool's offset/limit if needed).
  2. Extract every distinct NFL draft prospect that gets a real write-up, ranking, or tier — see schema below. If CONTEXT_TEXT is non-empty, treat its contents as additional rules that override or refine the schema rules below.
  3. Write the result as a JSON array (NOT wrapped in {"players": ...}) to pdfs/.cache/<stem>.<CONTEXT_HASH>.features.json using the Write tool.