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