# Studies

Some requests are questions before they are work: *is the Settings area finished?*, *why is the board slow on a
phone?*, *what would it take to drop Orca?* A **Study** answers one. It is a card with the Study recipe: its run reads
the code, starts the app and walks it, asks you what it needs, and ends with a **Proposal**: what it found, with
evidence, and the project and cards it suggests. You read the proposal on the card, steer it with comments the way
you'd review a pull request, and **Accept** turns it into a project with its cards in the Backlog.

A study never ships. It doesn't push, open a pull request or change the repository, and Andon never pushes or merges it for you.
Studies are cards, not a menu entry: there is no Studies page.

## What you need

- A **team with a repository**, and a **machine** that has the team's repository and can take a run (**Settings →
  Machines** shows it online).
- The org's **Study** recipe. Every org has it built in; if an admin archived it, Start work doesn't offer Study.
- On a machine that approves recipes one by one, approve it there first: `andon policy approve study`
  ([machine policy](https://andon-docs.pages.dev/reference/policy.md)).

## Start a study

1. Press **Start work** (the filled row at the top of the left menu, the middle tab on a phone, or `W` anywhere
   outside a text field).
2. Type the question, as a sentence or a whole brief. Say what you want to know and what a good answer would contain.
   Paste or drop screenshots and files; they become the card's attachments.
3. Press **Study it first**, beside the main button. Or start the text with *study* ("Study why the board is slow on
   a phone"), or say *study it first* or *as a study* anywhere, and the main button reads **Study it**. The **Intent**
   pill has **Study** too.
4. Check the pills: the **team** (required), the **project** (the team's General unless you pick one), and the agent,
   model, machine and priority if you want other than the team's defaults.

Andon adds one card with the Study recipe and the request as its notes, starts its run and opens the card. If no
machine can take it yet, the card waits in the Backlog and a toast says so; press **Run** on the card later. To turn a
card you already have into a study, give it the Study recipe and run it.

[Start work](https://andon-docs.pages.dev/guide/start-work.md#study-it-first) has the box in full.

## While it runs

The study runs interactively, like a code change, so you can watch it on the card or open its terminal. It may:

- **ask you something**: the card shows *Waiting for you*, it appears in **Attention**, and you answer in the card's
  reply box;
- **build a working mock** of what it proposes, in a folder of its own outside the repository, to show in the
  proposal. The mock is never committed, and the folder goes to the Trash when the card reaches Done;
- **ask for a permission**, as any run does.

Every study carries a grey **Study** mark on the board, in the list, in ⌘K search and in Attention. Type
`recipe:study` in the filter bar to list every study, open and done, and press ⌘S to save it as an *All studies* view
([Views](https://andon-docs.pages.dev/guide/views.md)).

## Read the proposal

When the study finishes it publishes its proposal as a page and the card goes to **Review**; it also shows in
Attention as *Outputs ready*. From then on, opening the card (from the board, Attention, its link or the phone) shows
the proposal first:

- **The page**, in a sealed frame: the question, the answer, the findings with their evidence, the proposal, what it
  did *not* check, and the proposed cards. A mock, if the study built one, is a tab beside it; **Run and details** is
  the usual run view.
- **The conversation** beside it (under it on a narrow panel and on the phone): the history, what the study needs from
  you, and the reply box.
- **Proposed project** under the page: its name and description, and its cards in order. Each says which cards it
  comes *After*, and is marked *Migration* or *Protected paths* when its pull request will need a person to merge it
  ([repository settings](https://andon-docs.pages.dev/reference/repo-settings.md)). A card's *Notes* open under it. Nothing exists yet.
- **Open questions**, when the study left some, with the cards each one affects.

## Ask for a change

Under the page is a comment box. Write what should change ("Drop the phone cards; they're a separate project") and
press **Ask for a change** (⌘Enter). The study takes the comment in the same workspace and writes the next version: a
new page and a new set of proposed cards, which replace the current ones. The box waits while the study works.

To comment on one part only, **select text in the page** (a paragraph, heading or list item). The box shows *About
this part, under "heading"*, and the study changes that part and copies the rest word for word. The × drops the pin.

Each round is a version. **Version N of M** above the page lists them newest first, with what was asked for; an
earlier version opens as it was, read-only, with its mock and cards. From version 2 on, a line counts what changed
since the version before, the changed paragraphs are marked in the page, and the list shows each one before and
after. **Mark in the page** turns the marks off.

After five versions the study waits for you: accept the proposal, or reply in its conversation to keep going. To
answer an open question, reply in the conversation; the study revises its proposal with the answer.

## Accept or Dismiss

On the newest version, under the proposed cards:

1. **Edit the project's name** if you want another. A team can't have two projects with the same name.
2. **Untick the cards you don't want**, and **edit any title**. A dependency through an unticked card becomes one on
   what that card waited for, so the order holds.
3. **Open questions**, if any: choose *Answer them first* (Accept stays off; reply in the conversation) or *Accept
   anyway and write them onto the cards they affect*. A question that affects no ticked card goes into the project's
   description.
4. Read the line above the buttons: *Creates N cards and M dependencies in the Backlog, owned by you. Autopilot starts
   none of them; the study moves to Done.* If Accept is off, the line says why.
5. Press **Accept and create N cards**.

Accept makes the project in the study's team and puts the ticked cards in its **Backlog**, owned by you, with their
dependencies. They never land in Ready, so Autopilot starts nothing until you move them. A card that needs a migration
or touches protected paths gets a *Before it merges* note. The study's pages are approved and its card goes to
**Done**. If any part fails, nothing is created and the study stays in Review. A proposal holds at most 30 cards.

The proposal becomes the **project's plan**. The project page shows it under *Plan*, says *From a study* and links back
to the study's card, and runs in the project get it in their prompt. Andon also asks a machine with the team's
repository to open a pull request adding the plan as `.andon/plans/<project>/plan.md`; once that merges, the file is
the plan. A team that keeps plans out of its repository (search Settings for **Plans in the repository**) keeps it on
the board instead.

**Dismiss** (and confirm) closes the study with nothing created: it moves to Done, and its page stays on the card.

Then run the cards as you would any others: move them to Ready, or start them from the card.

## Write a good study

- **Ask one question**, and say what you'll do with the answer. "Is Settings finished, and what's left to call it
  done?" beats "Look at Settings".
- **Name the evidence you trust**: "walk it at 1440, 1024 and 390", "count the queries on the board page", "compare
  with the Linear import".
- **Bound it**: what's out of scope, and which parts of the app to leave alone.
- **Read the *Not checked* section** before you accept: it is what the study didn't verify.

## See also

- [Recipes](https://andon-docs.pages.dev/guide/recipes.md): the other built-in recipes, and how a card gets one.
- [How a study is kept from pushing](https://andon-docs.pages.dev/contributing/study-sandbox.md) and
  [Study proposals and run pages](https://andon-docs.pages.dev/contributing/run-sandboxing.md), for people changing that code.
