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

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

# Docs Interviewer

<!--toc:start-->
- [Docs Interviewer](#docs-interviewer)
  - [Phase 1 — Audit before asking](#phase-1-audit-before-asking)
  - [Phase 2 — Interview loop](#phase-2-interview-loop)
  - [Phase 3 — Write-back (incremental)](#phase-3-write-back-incremental)
  - [Phase 4 — Exit report](#phase-4-exit-report)
  - [Hard rules](#hard-rules)
<!--toc:end-->

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.