1---
2name: ideating-with-bdd
3description: >-
4 Guides collaborative discovery and formulation of behaviour through
5 structured conversation. Iterates back and forth with the user to refine
6 ideas into user stories and Gherkin scenarios. Use when the user wants to
7 ideate, plan, brainstorm, discover, figure out requirements, refine an
8 idea, think through behaviour, or says things like "let's figure out",
9 "what should this do", "help me think through", "let's plan", or "I want
10 to build". Also use when the user has a vague idea and needs help making
11 it concrete, or when they ask "what should the behaviour be". Works for
12 any language or framework. NOT for automating tests or writing
13 implementation code.
14license: GPL-3.0-or-later
15metadata:
16 author: Amolith <amolith@secluded.site>
17---
18
19Collaborative discovery of behaviour through structured conversation. The end
20product is a user story and Gherkin scenarios — not code, not files, just
21shared understanding captured in a precise format.
22
23## How this works
24
25The user has an idea, a problem, or a vague sense of something they want to
26build. Your job is to help them think it through. Surface the rules, find the
27edge cases, resolve the unknowns, and keep going until the behaviour is clear
28enough to express as a user story with Gherkin scenarios.
29
30Getting behaviour right before writing code is how you avoid building the wrong
31thing.
32
33## The conversation
34
35Example mapping gives you a useful mental model for structuring discovery:
36
37- **Story** — the capability under discussion
38- **Rules** — constraints and acceptance criteria that emerge
39- **Examples** — concrete illustrations of how each rule plays out
40- **Questions** — unknowns to resolve before moving forward
41
42Use this as scaffolding, not a script. Some conversations will follow it
43closely; others will wander productively into territory you didn't expect. Pay
44attention to what the user is telling you. If they're already clear on the
45rules and just need help with edge cases, don't make them re-explain the
46basics. If they're still fuzzy on what they even want, spend more time there
47before drilling into specifics. If they push back on a question, trust that
48they have a reason and move on.
49
50Think of it like an interview: you have a structure in mind, but you adapt
51based on signals. If someone hands you a detailed spec, jump ahead to poking
52holes in it. If they give you a one-liner, draw out the details.
53
54### What to do during discovery
55
561. **Understand the story.** What capability is the user describing? Who
57 benefits? Why does it matter? Get this clear before diving into details.
58
592. **Surface the rules.** What constraints govern this behaviour? What are the
60 acceptance criteria? Rules often hide in assumptions. "What happens
61 when...?" and "Does this also apply when...?" are your best questions.
62
633. **Find concrete examples.** For each rule, work out at least two or three
64 concrete examples, including edge cases. Use specific names, values, and
65 scenarios. "Alice has 3 items in her cart and removes one" tells you more
66 than "a user removes an item."
67
684. **Capture questions honestly.** When something is uncertain, say so. Don't
69 paper over unknowns with assumptions. Questions are output worth
70 capturing — they prevent building on guesses. If a question can't be
71 resolved now, mark it as deferred and move on.
72
735. **Challenge and refine.** Push back gently when something seems
74 underspecified or contradictory. "What if the user does X instead?" is not
75 being difficult, it's being thorough. But read the room: if the user has
76 clearly thought something through, don't relitigate it.
77
786. **Summarise periodically.** After exploring a rule or a cluster of examples,
79 reflect back what you've understood. Let the user correct you. This prevents
80 drift and surfaces misunderstandings early.
81
82### When discovery is done
83
84You'll know discovery is winding down when:
85
86- The rules are clear and the user isn't surfacing new ones
87- Each rule has concrete examples including at least one edge case
88- Open questions have been resolved or deliberately deferred
89- The user is confirming rather than correcting
90
91Don't rush this. If questions remain, say so. It's better to acknowledge a gap
92than to quietly fill it with an assumption.
93
94## Formulation
95
96Once the behaviour is understood, formulate it as a user story followed by
97Gherkin scenarios. Present this in the conversation. **Do not write files.**
98
99### User story
100
101Begin with a single user story:
102
103```
104As a [role],
105I want [capability],
106so that [benefit].
107```
108
109The story frames everything that follows. The Gherkin scenarios are the
110detailed specification of what this story means in practice.
111
112### Gherkin scenarios
113
114Write declarative Gherkin that describes _behaviour_, not implementation. A
115useful test: imagine it's 1922 and no computers exist. Would the scenario still
116make sense as a description of how something should work? If not, it's too
117coupled to implementation.
118
119```gherkin
120# Good — declarative, behaviour-focused
121Scenario: Clean worktree reports no changes
122 Given a worktree with no uncommitted changes
123 When the status is checked
124 Then the worktree is reported as clean
125
126# Bad — imperative, implementation-coupled
127Scenario: Clean worktree
128 Given I run "git status --porcelain" and it returns empty
129 When I call the Status function with the path "/tmp/wt"
130 Then the Clean field is set to true
131```
132
133Ask: "will this wording need to change if the implementation does?" If yes,
134rewrite it.
135
136### Structure
137
138- Use `Rule:` to group scenarios under a business rule. These map directly
139 from the rules you discovered.
140- Use `Background:` for shared preconditions (keep it short, ≤ 4 lines)
141- Use `Scenario Outline:` with `Examples:` when scenarios differ only in values
142- Avoid conjunction steps ("Given I have a repo and three worktrees"). Use
143 `And`.
144- Omit incidental details that don't affect the outcome
145- Use the same domain language the user used during discovery. If they said
146 "cancel", don't write "terminate".
147
148For full Gherkin syntax, see
149[references/gherkin-reference.md](references/gherkin-reference.md).
150
151### Anti-patterns
152
153- **Feature-coupled steps** — steps should be grouped by domain concept, not
154 by feature. A step like `Given a worktree with uncommitted changes` belongs
155 with worktree concepts, reusable across features.
156- **Conjunction steps** — don't combine multiple things into one step. Split
157 them with `And`.
158- **Incidental details** — don't include specifics that don't affect the
159 outcome. If the name doesn't matter, don't name it.
160- **Implementation coupling** — scenarios should survive refactors. "When the
161 status is checked" not "When I call Status()".
162
163### Review the formulation
164
165Present the user story and Gherkin to the user. Ask them to read it as a
166specification: "does this describe the behaviour you want?" This is their
167chance to catch misunderstandings before anyone writes code.
168
169Be prepared to iterate. Formulation often surfaces things that discovery
170missed. A scenario might reveal a rule nobody discussed, or an edge case
171nobody thought of. That's the process working as intended. Go back to discovery
172if needed, then reformulate.
173
174## After formulation
175
176Once the user confirms the user story and Gherkin scenarios are right, suggest
177acting on the result. What to suggest depends on context:
178
179- **Go project with gocuke**: Suggest using the
180 testing-with-gocuke-and-gherkin skill to automate the scenarios, writing
181 `.feature` files, wiring up step definitions, and driving implementation
182 through red/green TDD.
183- **Other languages/frameworks**: Suggest writing `.feature` files and
184 implementing the behaviour using whatever test framework fits the project.
185- **No existing test framework or Gherkin integration**: Suggest saving the
186 spec. Write it to a `.md` file in the project, add it to the user's notes
187 app, or implement the behaviours directly. The spec shouldn't just vanish
188 into the conversation history.
189
190The user might take one of these suggestions, propose something else, or
191decide they got what they needed from the conversation alone. All fine.
192
193**Do not start implementing or writing files.** Present the suggestion and
194wait. The boundary between "we've agreed on what to build" and "go build it"
195is the user's call, not yours. Only proceed when they explicitly say to.