Make and review your first change

A small change you can see is the quickest way to learn the everyday workflow: you ask for it, try the result, see which of your project's commands passed, and decide whether it joins your project. You don't need to read the code to do that.

Say your reading-list app shows only "No results" when a search finds nothing, and you'd like the message to help people try again.

Finish setup, then open a fresh session with your coding agent, in a project you can run yourself. If it has no search, pick another small wording change you can see. Allow time for your tests to run, plus a few minutes to try the result.

Tell your agent:

"When a search finds nothing, make the message more helpful, so people know to try a different search. Keep the search itself the same. Show me how to try it, explain what you checked, and wait for my review before landing it."

Any request works this way: say what should get better, what should stay the same, and how you'll review it.

Your agent makes the change in a worktree, a separate copy of the project on its own branch, so your shared branch, the trunk (usually main), stays untouched while it works.

When the new message works, your agent commits it and runs the gate: your project's own commands, such as its linter and tests, which must all pass before a change counts as finished. If a test still expects "No results", it fails, so your agent updates it and runs the gateGate↗The full set of checks your project requires before a change counts as finished. again, as Fix a red gate explains.

When the gate passes, your agent brings back a way to try the new message, what it checked, and a Proof line. Proof is discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project.'s record of which commands passed on one exact commit, so you can match the report to the version you try:

Proof: Gate passed for agent/empty-search-message-a18caf at c57fa9751cf5 · 2 files changed (+4 −3) vs main · View the full Proof: discern status --verbose

Say the new message reads "No books match that search. Try a different word." You know your search also finds books by author, so the message could say that too.

Ask:

"Which tests cover the search, what did you try yourself, and what's left for me to judge?"

Your agent's answer should keep the gate's results apart from what it tried by hand. The updated test confirms the new message appears, but it can't tell you whether the message is clear.

If your project has checkpoints, review questions your agent answers when certain files change, the Proof shows the answers. If your agent answers that a question isn't met, only you can let the change land, as Checkpoints explains.

A bigger change may call for a code review, depending on what it could affect.

Ask for the revision:

"Mention that people can also search by author, and bring back the checked result."

Your agent commits the new version in the same worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens. and runs the gate again, because the old Proof covered the old version. When it's right, say:

"I've reviewed the change. Land it."

discern checks the Proof and your permission before the change lands, joining the trunkTrunk↗Your project's shared branch, usually main, where finished changes land., because a passing gate doesn't land anything by itself. If another task lands first, that doesn't send your change back to the start: discern checks the two changes together and lands exactly what passed.

The result's first sentence says whether it landed, and if not, what comes next:

Landed agent/empty-search-message-a18caf at 836e25a02ef7 on main; its checkout, branch, and resources are gone.

The landed commit, 836e25a02ef7, is your revision, which the gate checked again. Releasing it to your users stays with your own release process.

Your improvement is on the trunk, with a record of what passed on it, and you've practiced the loop that stays useful as the work grows.