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 ondesign/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.mdfor the canonical structure.references/question-bank.mdfor section-specific prompts.