Concepts
Changes
Every edit to your product, from a one-word fix to a new feature, is a change. A change can't be built until its lines are approved, and it can't land until each scenario it touches has evidence at its pull request head.
What a change holds
A change is one request and everything that follows from it. It holds:
- The request: the sentence you typed, or the push or finding that started it.
- The brief: your sentence, plus the details it left out.
- The proposals: exact edits to the spec, each one a line you approve or reject.
- The pull requests: one for the spec and one for each code repository the change touches.
- The evidence: the test runs and screenshots that prove each scenario.
- The events: everything that happened to the change, in order, with who or what did it.
A change is known by its pull requests and the commits they hold. That's how Babbit tells a change's own commits from a push someone made directly.
The five steps
The change screen shows five steps across the top. Each step lights with the time it happened; a skipped step is struck through.
| Step | What happens | Who acts |
|---|---|---|
| Asked | Babbit writes the brief and asks for anything only a person can give. The Product agent reads the spec and code and proposes spec edits. | Product agent |
| Approved | You approve or reject each proposed line. The approval binds to the content of those lines, not to a commit. | You |
| Built | The Code Writing agent writes code and a test per scenario in its workspace, then hands off. It sees the approved spec, never your sentence, so how a change was phrased can't steer the code. Babbit opens the pull requests. | Code Writing agent |
| Verified | Babbit runs each scenario's test at its pull request's head. A new scenario's test must fail before the change and pass after it. The Verify agent captures the app before and after. | Babbit, Verify agent |
| Live | Babbit merges the spec, then the code, and moves the release through preprod to prod. See How a release moves. | You confirm, Babbit acts |
A drift change, one that starts from a push nobody's change explains, shows different steps: Pushed, Described, Decide, Verified and Kept. See Keeping spec and code in sync.
The brief
The moment you press Enter, Babbit adds the details your sentence left out:
- The asks. Independent asks in one sentence become separate changes.
- The tier it's for: dev, preprod or prod. A merged change isn't deployed until a release reaches that tier.
- What done means, and how it will be verified.
- When to stop.
Under the brief, one line says which agent, model and effort Babbit chose for the work, and why. A short, casual sentence is the right way to use the change bar; the brief carries the rest.
The state card
Under the title, a state card always answers three questions: where the change stands, how long it has been there, and what, if anything, it needs from you. The card offers at most one action:
| Action | When you see it |
|---|---|
| Approve all | The proposals are ready for review. |
| Merge & release | Every scenario has its evidence and the change is ready to land and deploy. It reads Merge when nothing deploys from the change. |
| Apply change | A Manage change is ready to apply to your agents. |
| Promote | A release is held and waits for someone allowed to approve production. |
| Retry | A step failed for a reason a retry can fix. |
| Resume | The change stalled: its workspace stopped answering or its session ended without a handoff. |
Request changes and Cancel are always available while the change is open.
Gates: when a change needs you
Anything that needs a person is asked for once, together, before the work it blocks. A run never stalls halfway on something it could have asked for at the start. While it waits, the change reads Needs you and its workspace is stopped, so waiting costs nothing.
| Gate | Asked when |
|---|---|
| A key | The code calls a service, such as a payments API, and Babbit holds no key for it on that tier. |
| A sign-in | The code connects to an account through OAuth, such as a customer's calendar. |
| A question | The Code Writing agent needs a decision the spec doesn't answer. |
| Already does this | A new scenario's test already passes before any code changed. See Already does this. |
To answer one, see Answer what the change needs.
When a change goes back
Some events send a change back to an earlier step. None of them needs you to do anything.
- A test fails. The change returns to Code Writing with the failing output.
- A pull request moves. Evidence is only valid at the head of a pull request. A new commit sends the change back to verification, and every scenario light on the change goes hollow until verification runs again.
- Main moves. When another change lands first, a ready change goes back through verification against the new main.
- A merge conflicts. The change returns to Code Writing to resolve it.
When you click Request changes, the change goes back to the Product agent with your sentence, and you review the lines again.
How a change ends
A change ends in one of three ways:
- Done: every pull request merged. Babbit ends the change's workspaces.
- Cancelled: someone cancelled it before it finished.
- Landed partial: the spec merged but a code pull request was refused. The change's tier lights go hollow, because no tier has been earned, and one button reverts the spec commit.
A done change is not necessarily live. It rides in a release, and the release moves through the tiers. See Tiers, releases and hosting.
Changes that touch several repositories
When a project has more than one code repository, a change that touches two of them becomes a change set: one spec pull request and one code pull request per repository. The set is held behind a single required check until every pull request is green. Then the spec lands first and the code follows, in order. While the set lands, the change shows how many pull requests have merged, such as 0/2, and which one failed.
Find your changes
The Changes screen groups every change by whose move it is:
- Your turn: changes waiting on a decision, then failures.
- In progress: changes that are working or waiting on something outside you.
- Live: changes that are live, or live but not verified.
- Ended: folded away until you open it.
The strip at the top of Build and the bell in the toolbar open the same groups.
Related
- Describe and review a change: the change screen, tab by tab.
- Change and release states: every stage and event.