Collaborative Design Document
Goal
Interview the user section by section to produce a design document. Use AskUserQuestion tool if available. IMPORTANT: Write the current state to design-docs/ after each section. Adapt the interview to feature complexity.
Output File
- Path:
design-docs/ - Name:
NNN-short-kebab-title.md—NNNis zero-padded (e.g.001,002) - Sequence: List files in
design-docs/, take highest number, increment. Empty folder → start at001 - Title: Derive short kebab-case title from the feature description (ask user first)
Interview Process
For each section:
- Explain the section and what information is needed
- Ask targeted questions to gather it
- Summarize and propose draft content
- Ask user to confirm or correct before moving on
If the user answers something that belongs to a later section, acknowledge it and say you'll add it when you reach that section.
Section Order and Prompts
1. Goals
Ask: *What problem are we solving? Why does this feature matter?*
2. Non-Goals
Ask: *What is explicitly out of scope? What might people assume is included but is not?*
3. Desired Behavior
Ask: *Describe the user-visible behavior. What does the user see, click, or experience? Walk through the scenarios step by step.*
Format as a bullet list of concrete, observable behaviors.
4. Design
Ask: *How should this be implemented at a high level? What components, services, or data structures are involved?*
4a. Diagram
Produce a Mermaid flowchart of key components and interactions.
Legend:
- Square corners = Angular components
- Round corners = Angular services
- Arrows:
methodName({param1: Type1}): ReturnType [input1: Type1]= Angular inputs(output1: Type1)= Angular outputs- Use
<br>in labels to avoid truncation
Show diagram to user and ask for corrections.
4b. Implementation Details
Ask: *Any algorithms, edge cases, or conventions?* Leave empty if nothing to add.
5. Testing Strategy
Ask: *For each component or unit from the design, what behaviors are important to test?*
Format: grouped by component/unit, each scenario with a descriptive name and arrange/act/assert steps.
Example:
## Cart component
### Displays cart items:
- Arrange fake cart repository to return 3 items: keyboard, mouse, monitor.
- Mount `Cart` component.
- Assert 3 items displayed with labels: "Keyboard", "Mouse", "Monitor".6. PR Plan
Propose ordered, incremental PRs that:
- Never break existing behavior
- Are independently reviewable and mergeable
- Keep diffs focused
Rules:
- Scaffolding PR: If many new files, put WIP scaffolding in its own PR
- Pre-tidy-up PR: If interfaces must change, do backward-compatible changes first (optional params, deprecations)
- Feature PRs: Each adds one slice of user-visible or testable functionality
Include a Mermaid flowchart of PR dependencies. List each PR with a short description. Ask for feedback.
7. Alternatives Considered
Ask: *Did we consider other approaches? Why were they rejected?*
8. Kitchen Sink
Ask: *Anything else — open questions, risks, future ideas?* Leave empty if nothing.
Final Step
Assemble the full doc from the template below, write to the output file, show the user the path.
Template
# Goals
{goals}
# Non-Goals
{non_goals}
# Desired Behavior
{desired_behavior}
# Design
{design}
## Diagram
{diagram}
## Implementation Details
{implementation_details}
# Testing Strategy
{testing_strategy}
# PR Plan
{pr_dependency_diagram}
{pr_details}
# Alternatives Considered
{alternatives}
# Kitchen Sink
{kitchen_sink}