Interview playbook

For knowledge-transfer interviews — most commonly used before a maintainer leaves, retires, or moves off a project, but applicable any time a specific person is the last remaining source for something the code can't explain.

Analysis always comes first

Run retrospective analysis (retrospective-analysis.md) to build a gap list before the interview, regardless of which technique below is used for the conversation itself. It's what makes prioritization possible when time is short, and it's what a free-narration session gets checked against afterward to find what still needs a targeted follow-up.

Two techniques, chosen by the interviewee and the gaps — not always the same one

Targeted questions — the default when the gaps are specific and narrow, or time is short. Ask about something specific and observed, not a category. Never open with a generic "tell me about this system" questionnaire when this technique is the right fit — a scripted, specific question gets a specific memory back; a vague one gets a vague summary.

Ask about something specific and observed, not a category. "Why does X wait for Y" beats "explain the sync system."
Where a rejected alternative is suspected (from a comment, an old branch, a commit that was reverted), ask about it directly: "Was Z considered instead? What happened?"
Where the answer might reveal a constraint that no longer applies, ask: "Is this still true today, or was it true when this was written?" Stale constraints that outlived their reason are common and worth flagging as candidates for re-evaluation, not just documenting as permanent.
Leave room for the interviewee to raise something not on the prepared list — the gap analysis is a starting point, not a script to follow rigidly.

Free narration — a better fit when the knowledge is broad and tacit rather than narrowly scoped: someone who's maintained the same system, sometimes for decades, and whose understanding isn't organized around "what the code can't explain" the way a gap list is. A scripted question list can actually suppress recall here — the interviewee has to guess what's being asked about, instead of just telling the story their own way, and the most valuable detail often surfaces in a tangent that no specific question would have triggered. Open with something like "tell me about this system, start wherever you want" and let them talk.

The agent's job during free narration is different from targeted questioning:

Don't interrupt the flow for minor clarifications — let tangents run; tacit knowledge often surfaces exactly in the tangents, not in direct answers to direct questions.
Extract decision-forks as they come up organically (what was tried, what was chosen, what was rejected, and why), using the same structure as any other entry — it's just being extracted from flowing narration instead of a directed answer.
Ask a clarifying follow-up only when something is genuinely ambiguous, or when a claim needs pinning down for the confirmed/inferred classification — not to redirect the story back to an agenda.
After the narration (or at a natural pause), cross-check what was covered against the gap list from analysis. Whatever wasn't covered becomes a targeted follow-up question afterward — the two techniques aren't mutually exclusive, and combining them (narrate first, then close remaining gaps with pointed questions) is usually stronger than either alone.

Prioritizing what to ask (targeted technique) or listen for (free narration)

Time with a knowledge holder is usually limited. Prioritize gaps by:

Risk — what would break, or break silently, if this is never documented and someone later "cleans it up" without knowing why it's there.
Exclusivity — what only this person seems to know, versus what could plausibly be reconstructed by someone else later.
Decision weight — architectural or structural choices that shaped a lot of what came after, versus small local workarounds.

Low-risk, easily-reconstructible, low-weight gaps can wait or be skipped if time is short.

After the interview

Summarize each answer back and get it confirmed before writing it down as "confirmed" — don't rely on your own paraphrase being accurate.
Write up answers into the relevant topic files immediately, while detail is fresh, same as continuous capture.
If some prepared questions didn't get answered (time ran out, the person didn't know either), leave them visibly as open/unknown in the relevant topic file rather than dropping them silently — a documented open question is still more useful than one that quietly disappears.

A note on tone

This is often a conversation with someone leaving a project they've spent years on. Treat it as capturing their knowledge for the project's benefit, not as an audit or an extraction exercise. The framing "help the next person avoid re-learning this the hard way" tends to land better than "we need to get this out of your head before you go."