Add clarification & brainstorming loop

Author: codeaholicguy

commands/review-design.md

@@ -13,6 +13,9 @@ Review the design documentation in `docs/ai/design/feature-{name}.md` (and the p
    - API/interface contracts (inputs, outputs, auth)
    - Major design decisions and trade-offs
    - Non-functional requirements that must be preserved
-3. Highlight inconsistencies, missing sections, or diagrams that need updates.
+3. **Clarify and explore (loop until converged)**:
+   - **Ask clarification questions** for every gap, inconsistency, or misalignment between requirements and design. Do not just list issues — actively ask specific questions to resolve them.
+   - **Brainstorm and explore options** — For key architecture decisions, trade-offs, or areas with multiple viable approaches, proactively brainstorm alternatives. Present options with pros/cons and trade-offs. Challenge assumptions and surface creative alternatives.
+   - **Repeat** — Continue looping until the user is satisfied with the chosen approach and no open questions remain.
 4. **Store Reusable Knowledge** — Persist approved design patterns/constraints with `npx ai-devkit@latest memory store ...` when they will help future work.
 5. **Next Command Guidance** — If requirements gaps are found, return to `/review-requirements`; if design is sound, continue to `/execute-plan`.

commands/review-requirements.md

@@ -11,6 +11,9 @@ Review `docs/ai/requirements/feature-{name}.md` and the project-level template `
    - Primary user stories & critical flows
    - Constraints, assumptions, open questions
    - Any missing sections or deviations from the template
-3. Identify gaps or contradictions and suggest clarifications.
+3. **Clarify and explore (loop until converged)**:
+   - **Ask clarification questions** for every gap, contradiction, or ambiguity. Do not just list issues — actively ask specific questions to resolve them.
+   - **Brainstorm and explore options** — For key decisions, trade-offs, or areas with multiple viable approaches, proactively brainstorm alternatives. Present options with pros/cons and trade-offs. Challenge assumptions and surface creative alternatives.
+   - **Repeat** — Continue looping until the user is satisfied with the chosen approach and no open questions remain.
 4. **Store Reusable Knowledge** — If new reusable requirement conventions are agreed, store them with `npx ai-devkit@latest memory store ...`.
 5. **Next Command Guidance** — If fundamentals are missing, go back to `/new-requirement`; otherwise continue to `/review-design`.

packages/cli/templates/commands/review-design.md

@@ -13,6 +13,9 @@ Review the design documentation in `{{docsDir}}/design/feature-{name}.md` (and t
    - API/interface contracts (inputs, outputs, auth)
    - Major design decisions and trade-offs
    - Non-functional requirements that must be preserved
-3. Highlight inconsistencies, missing sections, or diagrams that need updates.
+3. **Clarify and explore (loop until converged)**:
+   - **Ask clarification questions** for every gap, inconsistency, or misalignment between requirements and design. Do not just list issues — actively ask specific questions to resolve them.
+   - **Brainstorm and explore options** — For key architecture decisions, trade-offs, or areas with multiple viable approaches, proactively brainstorm alternatives. Present options with pros/cons and trade-offs. Challenge assumptions and surface creative alternatives.
+   - **Repeat** — Continue looping until the user is satisfied with the chosen approach and no open questions remain.
 4. **Store Reusable Knowledge** — Persist approved design patterns/constraints with `npx ai-devkit@latest memory store ...` when they will help future work.
 5. **Next Command Guidance** — If requirements gaps are found, return to `/review-requirements`; if design is sound, continue to `/execute-plan`.

packages/cli/templates/commands/review-requirements.md

@@ -11,6 +11,9 @@ Review `{{docsDir}}/requirements/feature-{name}.md` and the project-level templa
    - Primary user stories & critical flows
    - Constraints, assumptions, open questions
    - Any missing sections or deviations from the template
-3. Identify gaps or contradictions and suggest clarifications.
+3. **Clarify and explore (loop until converged)**:
+   - **Ask clarification questions** for every gap, contradiction, or ambiguity. Do not just list issues — actively ask specific questions to resolve them.
+   - **Brainstorm and explore options** — For key decisions, trade-offs, or areas with multiple viable approaches, proactively brainstorm alternatives. Present options with pros/cons and trade-offs. Challenge assumptions and surface creative alternatives.
+   - **Repeat** — Continue looping until the user is satisfied with the chosen approach and no open questions remain.
 4. **Store Reusable Knowledge** — If new reusable requirement conventions are agreed, store them with `npx ai-devkit@latest memory store ...`.
 5. **Next Command Guidance** — If fundamentals are missing, go back to `/new-requirement`; otherwise continue to `/review-design`.

skills/dev-lifecycle/references/review-design.md

@@ -5,8 +5,11 @@ Review `docs/ai/design/feature-{name}.md` for completeness and fit against requi
 1. **Search memory** for relevant architecture patterns or past decisions.
 2. **Cross-check against requirements** — read `docs/ai/requirements/feature-{name}.md` and verify every goal, user story, and constraint has corresponding design coverage. Flag uncovered requirements.
 3. **Review completeness** — architecture (mermaid diagram), components, technology choices, data models, API contracts, design trade-offs, non-functional requirements.
-4. **Ask clarification questions** for every gap or misalignment between requirements and design. Do not just list issues — actively ask specific questions. Example: "Requirements mention offline support but design has no caching — should we add one?"
-5. **Update** the design doc with clarified decisions.
+4. **Clarify and explore (loop until converged)**:
+   - **Ask clarification questions** for every gap or misalignment between requirements and design. Do not just list issues — actively ask specific questions. Example: "Requirements mention offline support but design has no caching — should we add one?"
+   - **Brainstorm and explore options** — For key architecture decisions, trade-offs, or areas with multiple viable approaches, proactively brainstorm alternatives. Present options with pros/cons and trade-offs. Don't just accept the first approach — challenge assumptions and surface creative alternatives.
+   - **Repeat** — Clarifying answers may reveal new trade-offs worth exploring, and brainstorming may surface new questions. Continue looping until the user is satisfied with the chosen approach and no open questions remain.
+5. **Update** the design doc with clarified decisions and chosen options.
 6. **Store** clarified architecture decisions in memory.
 7. **Summarize** requirements coverage, completeness assessment, updates made, remaining gaps.
 

skills/dev-lifecycle/references/review-requirements.md

@@ -4,8 +4,11 @@ Review `docs/ai/requirements/feature-{name}.md` against the `README.md` template
 
 1. **Search memory** for relevant conventions or past patterns.
 2. **Review** each section: problem statement, goals/non-goals, success criteria, user stories, constraints, open questions, template compliance.
-3. **Ask clarification questions** for every gap, contradiction, or ambiguity. Do not just list issues — actively ask specific questions to resolve them. Example: "Success criteria say 'fast' — what's the target latency?"
-4. **Update** the requirements doc with clarified answers.
+3. **Clarify and explore (loop until converged)**:
+   - **Ask clarification questions** for every gap, contradiction, or ambiguity. Do not just list issues — actively ask specific questions to resolve them. Example: "Success criteria say 'fast' — what's the target latency?"
+   - **Brainstorm and explore options** — For key decisions, trade-offs, or areas with multiple viable approaches, proactively brainstorm alternatives. Present options with pros/cons and trade-offs. Don't just accept the first approach — challenge assumptions and surface creative alternatives.
+   - **Repeat** — Clarifying answers may reveal new trade-offs worth exploring, and brainstorming may surface new questions. Continue looping until the user is satisfied with the chosen approach and no open questions remain.
+4. **Update** the requirements doc with clarified answers and chosen options.
 5. **Store** clarifications in memory.
 6. **Summarize** what was validated, what was updated, remaining open items.