sdd-brainstorm

Generates SDD discovery reports with Gherkin scenarios through interactive requirements interviews.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/phm-aguiar/test_documentacao --skill sdd-brainstorm-phm-aguiar
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sdd-brainstorm
Source: https://github.com/phm-aguiar/test_documentacao/tree/main/.claude/skills/sdd-brainstorm
Command: npx skills add https://github.com/phm-aguiar/test_documentacao --skill sdd-brainstorm-phm-aguiar

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires sentence-transformers, and includes assets (resource) components.

What problem does it solve? Starting feature development without clear requirements leads to undefined error behavior, missing test contracts, and decisions that ignore existing codebase patterns. This Skill runs a structured discovery interview that produces an approved ADR+PRD hybrid report before any implementation begins. ## Core Features & Use Cases - Interactive Requirements Interview: Asks one question at a time across dimensions like purpose, scope, constraints, and failure scenarios, using multiple-choice prompts where possible. - Mandatory Cross-Reference: Searches the wiki index and scans the codebase with grep before interviewing, so decisions reuse existing patterns instead of ignoring them. - Quality-Gated Discovery Report: Generates a report in reports/ with Gherkin scenarios (minimum 3 success, 2 failure, 1 edge case), architectural decisions, and anticipated tech debt, iterating until the quality score reaches 20/25. - Use Case: A developer says "vamos pensar numa feature de notificações". The Skill interviews them, documents success and failure scenarios in Gherkin, scores the discovery report, and only after explicit approval hands off to the spec generation step. ## Quick Start Ask the assistant to brainstorm a new feature idea and it will interview you, cross-reference the wiki and codebase, and produce a scored discovery report in the reports directory.

Frequently Asked Questions about sdd-brainstorm

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a structured feature discovery interview before writing code?▼

Trigger the brainstorm workflow with a feature idea, and it interviews you one question at a time across purpose, scope, constraints, and failure scenarios. The output is a discovery report with Gherkin scenarios that must score at least 20/25 before approval.

What is a discovery report in spec-driven development?▼

A discovery report is an ADR+PRD hybrid document capturing context, functional and non-functional requirements, Gherkin scenarios, architectural decisions, and anticipated tech debt. It serves as the approved input for deriving the formal spec.md used by the implementation pipeline.

How many Gherkin scenarios does a discovery report need?▼

The quality gate requires at least 3 success scenarios, 2 failure scenarios, and 1 edge case, all with complete Given/When/Then steps. Failure scenarios must specify the exact error message and confirm system state remains unchanged.

Does the brainstorm step check existing code before proposing a design?▼

Yes, cross-referencing is mandatory. It searches the wiki index for relevant patterns and greps the codebase for related files, then documents findings and implications directly in the discovery report's cross-reference section.

What happens if the discovery report quality score is below 20?▼

The workflow shows the score per dimension, asks follow-up questions for any dimension scoring below 3, updates the report, and recalculates. This loop repeats until the total reaches at least 20 out of 25.

When should I not use an interactive discovery interview?▼

Skip it for trivial bug fixes or changes with already-approved specs, since the workflow enforces a hard gate against implementation before spec approval. It is designed for new features where requirements, failure modes, and architectural trade-offs are still undefined.