From 3c22ff6dc5c2f71763443d14e4f69db2d6f48c87 Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Fri, 3 Jul 2026 14:05:59 -0400 Subject: [PATCH] docs(interviewer): add documentation for deep-interviewing user to enhance docs/resume sources --- .claude/commands/docs-interviewer.md | 101 +++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 .claude/commands/docs-interviewer.md diff --git a/.claude/commands/docs-interviewer.md b/.claude/commands/docs-interviewer.md new file mode 100644 index 0000000..b9559a1 --- /dev/null +++ b/.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 | ] +allowed-tools: Read, Edit, Write, Grep, Glob, Bash(git:*), Bash(yq:*) +--- + +# Docs Interviewer + + +- [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) + + +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 — "`. + +## 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.