Skip to content
AndonDocs
GitHub
Use the board / Memory, recipes and integrations

Studies

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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).

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 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).

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). 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