Yard Docs
Sign in
On this page

Investigations

Ask a question about your code and get the answer in a doc of its own, with the lines that prove it and a chat to go on, then start work, write a spec or build a prototype from it.

Updated November 3, 2026 · 5 min read

A research project is a question an agent answers by reading your repositories. It changes no code. The answer is a doc of its own, named "Investigate: " and the question, so the team reads it like any other doc and not only in a chat. There is no separate Investigate page or list: the doc is listed under Docs with the others. The doc's chat is the investigation's, for follow-up questions, and from the doc you can start work, write a spec or build a prototype.

Ask

Use the start box, on Home or with New project (⌘J) on any page:

  1. Write the question, for example "Why is sign-in slow?".
  2. Check the context: the chips (what you added, and what is ticked in a doc or selected on a canvas, and your sidebar's Pinned chip). + picks blocks from the docs' library or a canvas; Attach, then A repository, adds a repository.
  3. Choose Research project and press Start.

Yard makes the project, with a doc for the answer, and opens it. The doc is named "Investigate: " and the first line of the question ("Investigate: Why is sign-in slow?"). You need edit access, and the runner has to be online.

The repositories the agent reads are the repositories in the context (repository chips and repository blocks), read-only. With none in the context, it reads none, except a repository the question names; when the answer needs another one, it asks before reading it, as an open question or a question card. See which repositories the agent reads. Files you attach go with the question only: they are not put in a doc or on a canvas.

A failing check has Investigate on the Monitors page. It asks "Why does the check … fail at step N?" with the check, its steps and its last failing run as context. See monitors.

The doc

The doc starts with the question as a quote and three sections, which the agent fills:

  1. Answer: what is the case, then why.
  2. What it found: the findings as a short list, each naming the lines that prove it as a reference to the repository file.
  3. Open questions: a checklist of what the code could not settle and what a person has to decide.

When the evidence is spatial (many excerpts side by side, a flow, groups of files), the agent also makes a canvas for it and embeds it in the doc, under What it found. Most investigations have no canvas.

The doc is an ordinary doc: edit it, reference it from another doc, or tick it as context for work. In the sidebar it is a row under Docs. It makes no tab and no canvas of its own.

The bar under the doc's header

It reads When What it offers
Researching, with the step the agent is on A turn is running, or the agent asked you a question in the chat Nothing: answer in the chat if it asked.
Finished, "Answered in this doc. Use it for:" The turn ended and the Answer section has text Start work, Write spec, Build prototype
Stopped, with what happened The turn failed, was stopped, or ended with the Answer section empty Ask again

Ask again sends the question to the same chat once more. While an investigation runs, Home lists it under In progress as "Researching", and Open goes to its doc.

Go on from it

Start work, Write spec and Build prototype use the doc as context (and the blocks of a canvas embedded in it) and the question as the request:

  • Start work makes a project whose agent starts at once in its own branch, and opens it.
  • Write spec makes a project that begins with a spec to review, and opens it. See projects and specs.
  • Build prototype makes a prototype, listed under Prototypes, places it at the end of the doc and asks for its first round. See prototypes.

The agent ends its reply with one to three Suggested next step cards in the doc's chat: what to do, one sentence on why, and the same three buttons with the one it suggests first. A button on a card passes the card's title on as the request. Viewers see the cards and the bar without buttons.

Follow-up questions

Write in the doc's chat. The message goes to the same agent conversation, the bar reads Researching again, and the agent works in the same doc: it changes the sections when the answer changes and adds findings and open questions. It does not start another doc.

Research from before

An investigation made before investigations answered in docs keeps its tab, which is now a canvas like any other: its blocks and notes stay there. Build prototype from it makes the prototype under Prototypes, never on that canvas.

What research may do

  • A research project reads the workspace's copies of the repositories, which are read-only. It makes no project, no branch, no worktree and no pull request.
  • It writes only to its own doc, and to a canvas it makes for that doc.
  • It runs with your agent account, like any chat. The agent and model are the ones chosen with the start box's model pill, or the workspace's defaults.

Through the API

  • POST /v1/workspaces/{ws}/investigations asks: question, and optionally blocks, context, contextPaths, repos, attachments, monitorIds and the agent. It answers the investigation: its id, its docId and its state.
  • GET /v1/workspaces/{ws}/investigations lists the investigations you may open, newest first, with their state (running, finished or failed) and answer, the first lines of the Answer section.
  • POST /v1/investigations/{id}/continue goes on from one: as is work, spec or prototype.
  • A follow-up is a message in the investigation's chat (POST /v1/chats/{id}/messages).

See the API reference.

Was this page useful?
Edit this page