docs(interviewer): add documentation for deep-interviewing user to enhance docs/resume sources

.claude/commands/docs-interviewer.md

@@ -0,0 +1,101 @@
+---
+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.