OpenParable
Skip to content
← Back to skills

Design Doc Interviewer

Documents
design-doc-interviewer

Design Doc Interviewer is an Agent Skill for documents published in the liveloveapp/hashbrown repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Interview the user to turn a proposed product/engineering change into a structured design document. Use when the user asks to be interviewed, wants help clarifying a design, or wants a design doc produced from Q&A. Emphasize numbered questions (few at a time), capture requirements/constraints/UX/data/logic/testing, and output a clean design doc.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/liveloveapp/hashbrown/blob/HEAD/.codex/skills/design-doc-interviewer/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/design-doc-interviewer, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.