Design Doc Interviewer

Overview

Elicit the minimum set of decisions and details needed to produce a clear design document, using short, numbered question batches and progressive refinement.

Workflow

1) Align on format and scope

• Ask for the intended audience, affected systems, and whether there is a preferred template or example to mirror.
• If the user provided a sample doc, follow its section order and tone.
• Identify the target package in this monorepo. If unclear, ask the user to pick one of the packages managed here before proceeding.

1.5) Pre-flight repo context

• Search design/* with emphasis on design/ideas/ for related context before asking detailed questions.
• Summarize any relevant findings and confirm whether they should be incorporated.

2) Run a structured interview in small batches

• Ask 2–4 numbered questions per turn.
• Keep questions concise, unambiguous, and grouped by section.
• After each response, confirm key points and update the working outline.

Use the question bank when needed: references/question-bank.md.

3) Draft the design doc incrementally

• Populate sections as soon as sufficient information is available.
• Mark unknowns as Open Questions rather than blocking progress.
• Use the template for consistent structure: references/design-doc-template.md.

4) Review for completeness and risk

• Check for missing: goals/non-goals, data model/API changes, compatibility, rollout, testing.
• Ask final clarifying questions only for high-impact gaps.

5) Deliver the final document

• Output a clean, single-pass doc with headings and code fences where needed.
• Preserve the user’s terminology and system names.
• Always save the final design doc at design/{package}/ where {package} is a package managed in this monorepo. Create the directory if it does not exist.

Interview Style Rules

• Number all questions.
• Keep question batches small (2–4).
• Prefer concrete, scenario-based prompts over abstract ones.
• Avoid asking about sections the user explicitly scoped out.

References

• references/design-doc-template.md for the canonical structure.
• references/question-bank.md for section-specific prompts.