--- name: ideating-with-bdd description: >- Guides collaborative discovery and formulation of behaviour through structured conversation. Iterates back and forth with the user to refine ideas into user stories and Gherkin scenarios. Use when the user wants to ideate, plan, brainstorm, discover, figure out requirements, refine an idea, think through behaviour, or says things like "let's figure out", "what should this do", "help me think through", "let's plan", or "I want to build". Also use when the user has a vague idea and needs help making it concrete, or when they ask "what should the behaviour be". Works for any language or framework. NOT for automating tests or writing implementation code. license: GPL-3.0-or-later metadata: author: Amolith --- Collaborative discovery of behaviour through structured conversation. The end product is a user story and Gherkin scenarios — not code, not files, just shared understanding captured in a precise format. ## How this works The user has an idea, a problem, or a vague sense of something they want to build. Your job is to help them think it through. Surface the rules, find the edge cases, resolve the unknowns, and keep going until the behaviour is clear enough to express as a user story with Gherkin scenarios. Getting behaviour right before writing code is how you avoid building the wrong thing. ## The conversation Example mapping gives you a useful mental model for structuring discovery: - **Story** — the capability under discussion - **Rules** — constraints and acceptance criteria that emerge - **Examples** — concrete illustrations of how each rule plays out - **Questions** — unknowns to resolve before moving forward Use this as scaffolding, not a script. Some conversations will follow it closely; others will wander productively into territory you didn't expect. Pay attention to what the user is telling you. If they're already clear on the rules and just need help with edge cases, don't make them re-explain the basics. If they're still fuzzy on what they even want, spend more time there before drilling into specifics. If they push back on a question, trust that they have a reason and move on. Think of it like an interview: you have a structure in mind, but you adapt based on signals. If someone hands you a detailed spec, jump ahead to poking holes in it. If they give you a one-liner, draw out the details. ### What to do during discovery 1. **Understand the story.** What capability is the user describing? Who benefits? Why does it matter? Get this clear before diving into details. 2. **Surface the rules.** What constraints govern this behaviour? What are the acceptance criteria? Rules often hide in assumptions. "What happens when...?" and "Does this also apply when...?" are your best questions. 3. **Find concrete examples.** For each rule, work out at least two or three concrete examples, including edge cases. Use specific names, values, and scenarios. "Alice has 3 items in her cart and removes one" tells you more than "a user removes an item." 4. **Capture questions honestly.** When something is uncertain, say so. Don't paper over unknowns with assumptions. Questions are output worth capturing — they prevent building on guesses. If a question can't be resolved now, mark it as deferred and move on. 5. **Challenge and refine.** Push back gently when something seems underspecified or contradictory. "What if the user does X instead?" is not being difficult, it's being thorough. But read the room: if the user has clearly thought something through, don't relitigate it. 6. **Summarise periodically.** After exploring a rule or a cluster of examples, reflect back what you've understood. Let the user correct you. This prevents drift and surfaces misunderstandings early. ### When discovery is done You'll know discovery is winding down when: - The rules are clear and the user isn't surfacing new ones - Each rule has concrete examples including at least one edge case - Open questions have been resolved or deliberately deferred - The user is confirming rather than correcting Don't rush this. If questions remain, say so. It's better to acknowledge a gap than to quietly fill it with an assumption. ## Formulation Once the behaviour is understood, formulate it as a user story followed by Gherkin scenarios. Present this in the conversation. **Do not write files.** ### User story Begin with a single user story: ``` As a [role], I want [capability], so that [benefit]. ``` The story frames everything that follows. The Gherkin scenarios are the detailed specification of what this story means in practice. ### Gherkin scenarios Write declarative Gherkin that describes _behaviour_, not implementation. A useful test: imagine it's 1922 and no computers exist. Would the scenario still make sense as a description of how something should work? If not, it's too coupled to implementation. ```gherkin # Good — declarative, behaviour-focused Scenario: Clean worktree reports no changes Given a worktree with no uncommitted changes When the status is checked Then the worktree is reported as clean # Bad — imperative, implementation-coupled Scenario: Clean worktree Given I run "git status --porcelain" and it returns empty When I call the Status function with the path "/tmp/wt" Then the Clean field is set to true ``` Ask: "will this wording need to change if the implementation does?" If yes, rewrite it. ### Structure - Use `Rule:` to group scenarios under a business rule. These map directly from the rules you discovered. - Use `Background:` for shared preconditions (keep it short, ≤ 4 lines) - Use `Scenario Outline:` with `Examples:` when scenarios differ only in values - Avoid conjunction steps ("Given I have a repo and three worktrees"). Use `And`. - Omit incidental details that don't affect the outcome - Use the same domain language the user used during discovery. If they said "cancel", don't write "terminate". For full Gherkin syntax, see [references/gherkin-reference.md](references/gherkin-reference.md). ### Anti-patterns - **Feature-coupled steps** — steps should be grouped by domain concept, not by feature. A step like `Given a worktree with uncommitted changes` belongs with worktree concepts, reusable across features. - **Conjunction steps** — don't combine multiple things into one step. Split them with `And`. - **Incidental details** — don't include specifics that don't affect the outcome. If the name doesn't matter, don't name it. - **Implementation coupling** — scenarios should survive refactors. "When the status is checked" not "When I call Status()". ### Review the formulation Present the user story and Gherkin to the user. Ask them to read it as a specification: "does this describe the behaviour you want?" This is their chance to catch misunderstandings before anyone writes code. Be prepared to iterate. Formulation often surfaces things that discovery missed. A scenario might reveal a rule nobody discussed, or an edge case nobody thought of. That's the process working as intended. Go back to discovery if needed, then reformulate. ## After formulation Once the user confirms the user story and Gherkin scenarios are right, suggest acting on the result. What to suggest depends on context: - **Go project with gocuke**: Suggest using the testing-with-gocuke-and-gherkin skill to automate the scenarios, writing `.feature` files, wiring up step definitions, and driving implementation through red/green TDD. - **Other languages/frameworks**: Suggest writing `.feature` files and implementing the behaviour using whatever test framework fits the project. - **No existing test framework or Gherkin integration**: Suggest saving the spec. Write it to a `.md` file in the project, add it to the user's notes app, or implement the behaviours directly. The spec shouldn't just vanish into the conversation history. The user might take one of these suggestions, propose something else, or decide they got what they needed from the conversation alone. All fine. **Do not start implementing or writing files.** Present the suggestion and wait. The boundary between "we've agreed on what to build" and "go build it" is the user's call, not yours. Only proceed when they explicitly say to.