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.