Tools

From Ask to Spec

In years of product work I can count on one hand the times someone handed me a problem. What arrives is a solution (“add a split-shipment button”), a number someone wants moved (“cut split shipments 20%”), or a bug report. The problem is in there somewhere, but digging it out is the job.

The skill this tool teaches is not taking the ask at face value. A proposed solution is a bundle of claims about the problem: who has it, what they can’t do today, why this particular shape fixes it. Each claim is either something someone has seen, something someone has said, or something nobody has checked. Write the claims down, sort them by how you know, and the real problem is usually sitting among the ones nobody checked.

From there the steps are standard, and the order matters: problems, then how you’d know each is solved, then requirements that each trace to a problem, then concrete examples, then Gherkin. The checks along the way are opinionated and never block you. If you disagree with one, say why, and your reason goes into the exported file as a comment next to the scenario it affects.

If you started from a solution, the last step puts it back next to what you found and asks: built exactly as asked, how much of the real problem would it solve? When the answer is “some of it,” you don’t have to just say no. The requirements you wrote along the way are the counter-proposal.

What were you handed?

Nobody hands you a clean problem. You get a solution, a number someone wants moved, or a bug report, and the problem is buried inside it.

— Skip the unpacking. The problem checks still run, so if it's a solution in disguise, you'll hear about it.
›How this works, and what it doesn't do

Every check is a short, deterministic rule: a word list, a missing field, a count. There is no model reading your text, so the checks are deliberately conservative. A warning never blocks you. Proceed past one by saying why, and the reason goes into the exported file as a comment, so the decision is recorded next to the scenario it affects.

The fit verdict compares each part of the original solution with each problem you found, weighting problems by evidence: observed over reported over assumed. It needs every pair marked before it will say anything, and it says “can’t judge yet” when most problems are only assumed, because that is a different answer from “it doesn’t fit.”

Scenarios are generated by template: context becomes Given, the action becomes When, the outcome becomes Then. Examples that differ only in their numbers, dates or quoted values are offered as a Scenario Outline. The .feature file uses Gherkin’s Rule: keyword; older runners that don’t support it can take the flattened export instead.

Everything runs in your browser. Your session is saved in this browser’s storage and nowhere else. A share link carries the whole session in the part of the URL after the #, which browsers never send to a server.

Bugs are three different things

A bug tracker files three kinds of ticket under one label. A defect is a build that doesn’t match behavior everyone agreed on, and it’s the one case where you should go straight to a regression scenario. A missing requirement is a case nobody ever defined, so “fixing” it means deciding it, usually under pressure. A changed expectation is a feature request that found the fastest queue. Fixing it as a bug skips the question of whether it’s worth doing at all.

The question that sorts them is short: was the expected behavior ever specified or agreed? The tool asks it before anything else on the bug path, because each answer sends you somewhere different.

“Can’t judge yet” is an answer

When most of the problems behind a request are only assumed, the honest verdict on the solution isn’t “it doesn’t fit.” It’s “we don’t know enough to say.” Those lead to different conversations. The first is an argument about the solution; the second is a short piece of research, and it usually costs less than the argument. It’s the same distinction the Experiment Designer draws between no effect and no idea.

On the method

Example mapping, Given/When/Then and the Rule keyword come from the behavior-driven development community; the unpacking steps and the fit verdict are my own framing of how I’ve seen requests go wrong. The checks are word lists and counts, not a model, so they’ll miss things and occasionally flag something that’s fine. That’s why every warning can be overridden with a reason. Everything runs in your browser; nothing you write is sent anywhere.

Sources
  • Wynne, M. (2015). “Introducing Example Mapping.” Cucumber blog. — rules, examples and questions per story
  • North, D. (2006). “Introducing BDD.” Better Software. — Given/When/Then as a shared language for behavior
  • Adzic, G. (2011). Specification by Example. Manning. — concrete examples as the specification
  • Torres, T. (2021). Continuous Discovery Habits. Product Talk. — separating the opportunity from the solution