Concepts
Features, goals and scenarios
The spec is what your product does, written as examples that tests can check. It holds features, goals and scenarios, at most three goals to a feature, and it changes only through a change you approved.
The three parts
A spec is a tree of features. Each feature has goals, and each goal has scenarios.
| Part | What it is | Limit |
|---|---|---|
| Feature | A capability someone can see from outside the product, named with a verb and a noun: Redeem points, Invite a teammate. | At most three children, unless they are peers of one kind. |
| Goal | A quality the feature must have, stated as a rule: Redeeming never takes more points than the customer holds. | At most three per feature. |
| Scenario | One example of the feature at work: what someone does, and what they see. | None, but every scenario belongs to a goal. |
Goals are the rules. Scenarios are the examples that show the rules hold.
Scenarios are examples
A scenario is a single line with an action and an outcome:
Redeem 500 points → see a $5 credit on the next order.
A rule like "points convert at 100 to $1" is hard to check, and it's easy for two people to read it differently. An example is easy to check, and a few examples make the rule obvious: if 500 points is $5 and 1,000 points is $10, you can see the pattern without stating it.
This is why Babbit writes the spec as examples first:
- Examples are testable. Each scenario maps to a test, so the spec and its verification are the same list.
- Examples align people and agents. Everyone agrees on what goes in and what should come out, even when they would describe the rule differently.
- Examples change safely. Editing a scenario changes exactly one expected outcome, and Babbit knows which test proves it.
Every scenario carries the result of its last test run as a light: green when it passes, red when it fails, and hollow when it has no test yet.
What a scenario can carry
A scenario can name the conditions it runs under, shown as a chip before the action:
- A given: a starting state, such as
signed in as a viewer. - A tier: where the outcome must hold, such as
prod. - A measure: a target, such as a response time on a tier.
These are part of the line. Editing any of them is editing the scenario, and evidence for the old line no longer counts. See Evidence and verification.
What counts as a feature
A feature is something a user can see from the outside and would name with a verb and a noun. It has its own scenarios, and it could be shipped, verified or removed on its own.
Three things look like features and are not:
| Not a feature | Example | Where it belongs |
|---|---|---|
| A screen or region | A toolbar, a settings page | The capability the screen serves. |
| A stage or state | "Needs approval", "Loading" | Scenarios of the feature it is a stage of. |
| A control | A slider, a menu | Scenarios of the feature the control is part of. |
A feature with two real children has two. Babbit never pads a feature to three.
The rule of three
People hold three things in mind easily, so a feature holds at most three goals and three children. The Babbit MCP refuses any proposal that breaks the limit, so no agent can add a fourth:
- A fourth goal is refused. It has to become a child feature, merge into the goal it restates, or become a policy that applies across features.
- A fourth child is refused unless the feature's children are marked as peers of one kind, such as four payment methods. Otherwise the parent has to split.
Where a new feature goes
Today, the + button opens a change, and the Product agent proposes where the new feature goes as a line you approve like any other.
Placement with confidence
When a change adds a feature, Babbit will decide where in the tree it belongs and show how sure it is:
| Confidence | What you see |
|---|---|
| 0.8 or higher | The feature is placed. A chip shows where and how sure. |
| 0.5 to 0.8 | The feature is placed, with one line offering the runner-up: "or under Projects?" |
| Under 0.5 | Babbit asks Where does this go? with the three likeliest places. Nothing is proposed until you pick. |
It will also find when a sentence needs no new feature, because it already exists or it contradicts a goal. A sentence the spec already covers will open the line that covers it instead of proposing a copy, and a sentence that breaks a goal will be proposed as an edit to that goal.
Views of one feature
Each feature has views you switch between from its header:
- Product Spec: the goals and scenarios, written for people. This is where you edit intent.
- Implementation Spec: the same feature from the code's side, kept current by the Code Writing agent. Each scenario shows the test that proves it and the code path it runs through. Under it are the schema (the nouns the feature owns, in plain words), the tech stack it adds, and its boxes. You come here when you can't trust an outcome, not before.
- History: every change to the feature, newest first, with its evidence. See Edit the spec directly.
Where the spec lives
The spec is files in Git, on the newdev/spec branch of the first repository you connected. It only changes through an approved change, which Babbit merges for you. A person who edits the spec by hand on GitHub opens a change whose proposals are that edit, so even manual edits get reviewed. See GitHub, branches and check runs.
Related
- Edit the spec directly: edit a goal or scenario, restore an old version.
- Changes: how an edit to the spec becomes code.
- Glossary: every term on this page.