Take a goal on an existing codebase to a checked change, committed and pushed for review, in the desktop app or the CLI.

On this page

This guide takes one change on an existing repository from a written goal to a checked change pushed on a branch for review; the example adds ISO week-date support to a date parser in a Python service. Before you start, you need the desktop app or the CLI, the repository checked out on your computer, and a working test command.

Steps#

Write the goal as an outcome#

Say what should be true when the work is done, and name the constraints Ysra can’t infer:

Goal
Make parse_date() accept ISO week dates such as 2026-W39-5 and 2026-W39.
Keep the public signature unchanged. Existing callers must not change.
Add tests for the week-date forms and for invalid weeks (W00, W54).

If a ticket already lists acceptance criteria, paste them: your criteria are reviewed one by one against the final change. See Writing a brief.

Open the repository#

In the desktop app, choose the repository’s folder on the line under the message box; in the CLI, run ysra in the folder. See Start a thread.

Send the goal and confirm the plan#

Send the goal. The thread shows its plan and makes its first saved point, usually within minutes. This is the cheapest moment to correct course: steer now if the plan misreads the goal.

Use datetime.date.fromisocalendar rather than a hand-written week parser.

Read the result#

When the task ends, check three things before you commit:

Look at Why
Checks Which of your commands ran, on which version of the change, with what result
Acceptance review Each criterion, met or not, against the exact change
Pre-existing failures Anything broken before the change, reported separately

See Review and verification.

Commit and push#

Choose Commit… on the finished task, or say “commit”: Ysra commits on a new branch. Pushing asks first, every time. See Commit and push, or Commit, push and undo in the CLI.

The branch is on your remote, and your repository’s CI result is read back into the thread.

If it doesn’t work#

Symptom Why What to do
The same test keeps failing, and the task ends Didn't work When the same failure keeps coming back, the task stops instead of looping. Usually an environment need the goal didn’t mention (a service, a secret, a fixture). Read the last failure in the report, then steer with what it needs and Continue.
Ysra asks before installing something Installs need your OK. Approve it once. See Install tools with your OK.
The task paused: “I stopped at the limit set for this work. …” Credits ran out; the change, saved points and evidence are kept. Add credits and tell Ysra to continue. See When credits run out.
The plan misread the goal The goal left room for it. Steer, or go back to a saved point. See Steering and saved points.

More in Troubleshooting.

YsraDocs