cv/.claude/commands/docs-interviewer.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Deep-interview the user to enhance docs/ resume sources with concrete, verified content	optional focus experience | projects | skills | about | <specific entry name>	Read, Edit, Write, Grep, Glob, Bash(git:*), Bash(yq:*)

Docs Interviewer

• Docs Interviewer
  • Phase 1 — Audit before asking
  • Phase 2 — Interview loop
  • Phase 3 — Write-back (incremental)
  • Phase 4 — Exit report
  • Hard rules

Enhance the canonical resume data under docs/ by interviewing me. The goal is NOT to reword what's there — it's to extract information that isn't captured yet: metrics, scope, constraints, decisions, and outcomes. The .tex variants consume these files, so quality here compounds into every tailored resume.

Focus scope: $ARGUMENTS (if empty, cover all of docs/; if a directory or entry name is given, go deep on just that)

Phase 1 — Audit before asking

Read every YAML file in scope under docs/about, docs/experience, docs/projects, docs/skills. For each entry, grade every bullet/claim against this rubric and build a private gap list:

Grade	Meaning
A	Concrete action + quantified outcome + clear scope ("Reduced p99 auth latency 40% by moving session validation into a WASM enclave")
B	Concrete action, no metric or fuzzy scope
C	Vague responsibility language ("worked on", "helped with", "contributed to")
D	Naked tech mention with no claim attached, or skill listed with zero supporting evidence anywhere in docs/

Also flag structural gaps: experiences with < 3 bullets, projects missing stack/outcome/status fields, skills in docs/skills unsupported by any experience or project, and timeline holes.

Do not ask about anything already graded A. Interview time is scarce.

Phase 2 — Interview loop

Work the gap list highest-impact first (recent + senior + relevant to my target roles: founding/protocol/crypto/mobile engineering).

Rules of engagement:

• One entry at a time, max 3 questions per message. Never dump a 20-question survey. This is a conversation, not a form.
• Ask questions a good journalist would. For each weak bullet, dig for:
  • Scale: users, requests/sec, dollars, data volume, team size, time saved
  • Baseline: what was true before? ("faster" than what?)
  • Hard part: what almost didn't work, what did you reject and why — design decisions often make better bullets than features shipped
  • Ownership: what was YOURS vs. the team's — be precise, this guards against both understating and overstating
  • Aftermath: did it ship, get adopted, get cited, still run today?
• If I answer "I don't remember the number": offer estimation scaffolding ("was it closer to 10 or 10,000 users?") and record estimates as ranges with an approx: true flag — never silently convert a guess into a hard number.
• If I answer "there's no metric": that's fine. Ask for a qualitative anchor instead (before/after behavior, who relied on it). Don't manufacture one.
• Push back when answers are still vague. "It improved developer experience" gets a follow-up, not a nod.
• Periodically check for missing entries, not just weak ones: "Anything you built in this era that isn't in docs/ at all? Side projects, internal tools, talks, open source?"

Phase 3 — Write-back (incremental)

After each entry is exhausted (not at the very end — context is freshest now):

1. Show me the proposed YAML diff for that entry: enhanced bullets, new fields (metrics, scale, approx, keywords, evidence), any new entries.
2. Bullets go in as content-rich but style-neutral — capture facts and numbers; leave verb polish and JD-mirroring to /resume-optimize.
3. On my approval, Edit the file. Never write unapproved content.
4. Keep skills honest: every skill in docs/skills should gain an evidence pointer to at least one experience/project entry, or get flagged for removal.

Commit at natural checkpoints: git add docs/ && git commit -m "docs: interview pass — <entry>".

Phase 4 — Exit report

When the gap list is exhausted or I call it:

• Grade distribution before → after (e.g., "14 C-grade bullets → 3")
• New metrics captured, new entries added
• Remaining gaps I declined or deferred, so the next session can resume there
• Any claims flagged approx: true I should verify against real data later

Hard rules

• Every recorded fact must come from my answers or existing docs/. No inference, no embellishment, no rounding a range up.
• If I contradict something already in docs/, surface the conflict and ask which is right — don't silently pick one.
• Session is resumable: if we stop mid-list, write remaining gap list to docs/.interview-queue.yaml so the next invocation picks up where we left off.