---
title: "Edit sessions"
description: "Change existing spec files with the AI, review each change as a diff, and keep or discard it."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.myspec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit sessions

An **Edit session** is a chat in which the AI changes spec files that already
exist: it fixes issues, adds detail or restructures content. You review every
change before you keep it.

## When to use Edit

| You want to | Use |
|---|---|
| Create specs for a new product or feature | A [Generate session](/guides/generate-sessions/) |
| Change, extend or fix spec files you already have | An Edit session |
| Change a few words yourself | An Edit session, using **Edit manually** on the file. See [View and edit spec files](/guides/spec-editor/). |
| Revise a stage in a Generate session that is still running | `/goback` in that session |

## Start an Edit session

1. **Open a new edit chat**

   Open your project. Under **Chats**, select the **Edit** tab, then **Edit**.
   If MySpec asks **What would you like to do?**, choose **Edit**.

   After a Generate session finishes, you can also select **Edit** on its
   **Session completed** card. The message box then starts with "I want to
   update spec", followed by the bundle's name.
2. **Check the methodology**

   Under **Edit methodology**, MySpec shows the edit workflow for your project
   type: **MySpec edit-workflow (v1)** for Greenfield projects and
   **MySpec edit-brownfield (v1)** for Brownfield projects. Projects of type
   **Auto** can pick either. When only one fits, you see a **Using …** badge.
3. **Reference the files and describe the change**

   Type `@` or select **Reference a file** to point at the spec files to
   change, then say what to change in plain language. Send the message.

The AI writes in the language you use MySpec in, and the language is locked
once the session starts, as in a Generate session. See
[Language and AI model](/guides/generate-sessions/#language-and-ai-model).

Starting an Edit session, sending messages and accepting or discarding changes
need **Write** access on the project. With **Read** access you can open and
read an Edit session, but the message box is locked under a **Read-only
access** banner, and you can't use **Edit manually**. See
[What Read users see](/guides/teams-and-project-access/#what-read-users-see).

## The three steps

The welcome panel shows the steps of an Edit session:

| Step | What happens |
|---|---|
| **Reference** | Point the AI at the spec files you want to change: pick one or more files from the current bundle as the edit target. |
| **Describe** | Tell the AI what to change in plain language: fix issues, add missing detail, or restructure content across the referenced files. |
| **Review** | The AI proposes each change as a reviewable diff. Accept, refine, or discard it before it's applied to your specs. |

### Pick the files

Reference each file you want changed with `@`. The list has sections for
**Spec Files**, **Attachments** and, when you share a folder, **Local
Workspace**. You can also drag a spec file from the file explorer onto the
message box. If you only name a bundle or a file, the AI can look it up
itself.

Attachments you reference give the AI extra context. See
[Attachments and local files](/guides/attachments/).

### Describe the change

Be specific about what should change and where, for example "In
requirements.md, add an acceptance criterion to FR-003 for expired links". If
your request leaves something open, the AI asks a short round of
multiple-choice questions first. Answer them as you would in a Generate
session.

## Review the proposed changes

When the AI has made its changes, it shows a **Review changes** card with one
row per changed file. Each row shows the file, its path and the revisions it
moves between, such as **Rev 3 → 4**.

1. **Look at the diff**

   Select the eye icon (**Preview changes**) on a row. The file opens in diff
   mode, comparing the old revision with the new one.
2. **Choose Accept or Discard for each file**

   **Accept** keeps the change. **Discard** removes it and puts the file back
   to its previous revision.
3. **Submit**

   **Submit** becomes available once every file has a choice.

If someone saved a newer version of a file before you discarded the change, the
file is kept as it is, and the AI tells you so.

### Refine a change

After you submit, describe what else to change in the message box. The AI makes
another round of changes and shows a new **Review changes** card. You can
repeat this as often as you need in one session.

To make a small fix yourself, select the pencil icon (**Edit manually**) on a
spec file card in the chat. See [View and edit spec files](/guides/spec-editor/).

## Complete the session

Type `/complete` and press Enter. MySpec opens **Review changes before
completing**, which lists every spec file edited in the session, with
**View diff** for each one and a summary under **What changed in this
session**. Select **Complete session** to finish, or **Cancel** to keep
working.

When the session is complete, the chat shows **Session completed** with the
edited files, the revisions they moved between and a **Download** button for
each bundle. You can't send more messages in a completed session; start a new
Edit session for further changes.

In an Edit session you can also use `/btw` to ask a side question. `/goback` is
only for Generate sessions. See
[Slash commands](/guides/generate-sessions/#slash-commands).

## When the project has no spec files yet

An Edit session needs at least one spec file. If the project has none, MySpec
shows **No spec file yet**: "This project doesn't have any spec file to edit
yet. Start a Generate session to create your first spec, then come back and
edit it." Select **Switch to Generate** to start a Generate session, or **Back
to options**.

## Edit specs for an existing codebase

In a Brownfield project, the edit workflow checks your code before it changes a
spec. The AI reads the related code first, so you need to share your codebase
with the session: mount a folder in the browser or run the local MCP server's
`reverse` command. See [Work on an existing codebase](/guides/brownfield/#edit-specs-for-an-existing-codebase).

Source: https://docs.myspec.dev/guides/edit-sessions/index.mdx