---
title: Change an existing repository
description: A complete walkthrough — from a goal on an existing codebase to a draft pull request you can merge with confidence.
---

This guide follows one realistic change end to end: adding ISO week-date support
to a date parser in an existing Python service, and delivering it as a draft pull
request.

**You will need:** a connected repository with a working test command, and a
policy that allows `delivery_mode: draft_pr` (or permission to open the pull
request yourself).

## Step by step

<div class="steps" markdown>

### Write the goal as an outcome

Describe what should be true when the work is done, and name constraints Ysra
cannot infer:

```text title="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).
```

!!! tip "Acceptance criteria are yours to override"
    Ysra derives acceptance criteria from the goal. If you already have them — in
    a ticket, say — paste them in; explicit criteria are reviewed one by one
    against the final diff.

### Set a budget that matches the change

A focused change on a repository with a fast test suite usually needs a small
budget. The session stops and asks before exceeding it, so an underestimate
costs you a click, not a failed run.

### Watch the first checkpoint

Within a few minutes the session shows its plan and first checkpoint. 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.

### Review the evidence, not only the diff

When the session completes, check three things before delivering:

| Look at | Why |
|---|---|
| **Checks** | Which native commands ran, on which candidate, with what result. |
| **Acceptance review** | Each criterion, marked met or unmet against the exact diff. |
| **Pre-existing failures** | Anything already broken before the change, reported separately. |

### Deliver

With `delivery_mode: draft_pr`, Ysra opens the draft pull request itself. With
the default `preserve_only`, choose **Open PR** in the portal or the mobile app.
Either way, the pull request links back to the session report.

</div>

## When something goes wrong

??? failure "The session keeps failing the same test"
    Ysra stops after repeated identical outcomes and reports non-convergence.
    Read the last failure in the report: it is usually an environment need (a
    service, a secret, a fixture) the goal did not mention. Steer with that
    information and continue.

??? question "Ysra asks before installing a package"
    That is `package_installs: ask`. Approve it once in the session, or change
    the repository policy if the answer will always be yes.

See [Troubleshooting](../resources/troubleshooting.md) for more.