> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.orbi.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a request

> Tell Orbi what you want changed. Orbi reads your code, writes a draft for you to review, and starts once you hand it off.

You don't have to write the Issue yourself. On the status page (the page you land on after signing in), click **Write a request** and say what you want changed in a sentence or two. Orbi reads the code in your project and writes a draft, usually within one to two minutes. Nothing is created in your GitHub repository until you review the draft and hand it off.

## Start from a suggestion

**Review draft** on the status page opens a suggested draft that is already written. Read it, then **Hand off to Orbi**, or tell Orbi below what to change and review the revision first. Opening a suggestion does not create a GitHub Issue.

If the page says **You have another draft that hasn't been handed off:** with its title, **Open it** returns to that draft. Suggested drafts are kept separately from the request you wrote yourself.

## Write and hand off

1. On the status page, click **Write a request**. The button appears once a GitHub repository is [connected](https://cloud-docs.orbi.build/connect-repository.md). If you have connected several, use **Switch project** on the page to pick one.
2. Under **What would you like to change?**, describe it in plain words: a new feature, a bug fix, a text change. One sentence is enough; a longer description is fine too. Then click **Draft the request**.
3. Orbi reads your code and writes the draft. This usually takes one to two minutes, and the page shows **Writing the draft** meanwhile. For a project you have only just connected, Orbi first waits for its work environment to be [prepared](https://cloud-docs.orbi.build/provisioning.md), usually another 10–20 seconds. You can close the page; to come back, click **Write a request** on the status page and then **Open draft**. Sometimes Orbi asks you a few questions, either along with the draft or before writing it; see the next section.
4. Read the draft. It states what you asked for, what your users should see when it is done, what is left out, and how Orbi read anything your words left open.
5. Click **Hand off to Orbi**. This creates an Issue in your GitHub repository, and Orbi works from it. The page then shows **Handed off to Orbi** and **Usually starts within a minute**.

Two cases where the work does not start right away: you are out of free runs (see [Usage](#usage)), or the page shows **Not scheduled yet**. In the second case, follow the steps the status page shows, or [contact us](https://cloud-docs.orbi.build/troubleshooting.md#getting-help); nothing counts toward your free runs or quota while it waits, and you don't need to hand it off again.

## When Orbi isn't sure

If your request can be read more than one way, Orbi asks you rather than guessing. The questions and their options are listed under **Orbi chose these for you**, and Orbi has already picked the option it recommends for each. You will see one of two layouts:

* **A draft with questions under it.** The draft already uses the recommended answers, so if you agree you can hand it off without changing anything. If an answer isn't what you meant, pick another option, or choose **Other (write your own)** and type your own. Then click **Rewrite the draft**; it takes about a minute, and you can hand it off once the new draft is ready. Changed your mind? Click **undo your changes**.
* **Questions with no draft yet.** Pick your answers the same way, then click **Write the draft**.

To change anything else, write it in the box under the draft and click **Send**. Orbi rewrites the draft and keeps what you said before, so you don't have to repeat it.

## Add detail to an existing request

For an Issue at `ai-needs-detail`, click **Add the details** on the status page. **Add detail to a request** shows the original Issue number, **Orbi says it still needs these**, **What was written before**, and a **What to add** box. This page is tied to that Issue and has no project selector. When Orbi has already proposed a split or acceptance criteria for the Issue, the status page shows that proposal with a start button instead; see [troubleshooting](https://cloud-docs.orbi.build/troubleshooting.md#when-orbi-has-already-proposed-a-fix).

Write the missing detail and review the revised draft. Handing it off appends the confirmed detail to the original Issue, removes `ai-needs-detail` and adds `ai-ready`; it does not create another Issue. **Write another request** returns to the ordinary request page for a separate task.

## What gets created

When you hand off, Orbi creates a normal GitHub Issue in your connected repository. Its first line is `Submitted by @your-login via Orbi`, then a **View project status in Orbi** link, then the approved draft, word for word. On the status page it appears as a task, showing the Issue title.

The ordinary **Write a request** entry opens the project’s latest ordinary draft. Starting another request makes the new draft the one shown there. Suggested drafts have their own entry points. Unsubmitted drafts are kept for 7 days after their last change; Issues already handed off stay in GitHub.

## Usage

* Writing drafts doesn't use your free runs, and there is no separate limit on how many drafts you write.
* A task you hand off is counted the same way as an Issue you give Orbi any other way: on the free plan, a run only counts if the change is merged.
* **Free plan:** your free runs are a one-time allowance and do not reset monthly. When you have none left you can still write and hand off, but the task won't start. After you [subscribe](https://cloud-docs.orbi.build/billing.md), the task shows up on the status page among the Issues Orbi hasn't started; click the button next to it (such as **Try →**) to start it. You don't write it again.
* **Paid plans:** when this month's AI usage limit is reached, writing drafts stops too until the limit resets on the 1st of the next month. You won't be charged extra. See [Limits and quotas](https://cloud-docs.orbi.build/limits-and-quotas.md).

## When to write the Issue yourself

If you already know exactly what you want and can list how to check it, [creating the Issue on GitHub](https://cloud-docs.orbi.build/first-issue.md) is quicker. Write a request helps most when you know what you want solved but not where to change the code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.