> For the complete documentation index, see [llms.txt](https://docs.darcyiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.darcyiq.com/build/pipelines/reviewing-and-deciding.md). # Reviewing & Deciding Work your review queue, read what your agent found, and approve or return an item with the changes you need If you own a stage, the work comes to you already read. Your agent has been through the submission against your requirements and produced a verdict, reasons, and a list of what it thinks is wrong. Your job is the decision. {% hint style="success" %} **A queue that arrives pre-read**: Counsel opens Pipelines to find one item at her stage. The agent has already opened the contract, confirmed the renewal clause, and flagged that the liability cap is 24 months of fees rather than 12. She reads the finding, agrees, and returns the item — the reason is pre-filled from the open findings, so returning it takes one click and a sentence. {% endhint %} ## Your Queue The **Pipelines** home page opens on your own queue, split by what each group needs from you: | Section | What's in it | | -------------------------- | ----------------------------------------------------------- | | **Needs your decision** | Items where the agent has answered and is waiting on you | | **Returned to you** | Your own submissions that a stage sent back | | **Running at your stages** | Items whose review is still in progress — nothing to do yet | "Your stages" means every stage you own **or are an additional approver on**. You're also notified when work reaches you, so the queue is a place to work rather than a place to check. ## The Board Each pipeline has a **Board** tab with a column per stage, in review order, plus a **Done** column. A card sits in the column of the stage currently holding it, so the shape of the queue is the shape of the backlog. | Control | Options | | ------------- | ------------------------------------------------------------------------- | | **Filter** | All items · **Submitted by me** · **Needs you** | | **Sort** | Longest waiting · Recently updated · Newest · Oldest | | **Items tab** | The same submissions as a searchable, filterable list rather than a board | **Longest waiting** is the one to sort by when you're catching up — it surfaces what's been sitting rather than what's newest. ## Reading a Review Open an item to get the **Review**, **Files**, and **Activity** tabs. The Review tab carries, for the current stage: | Element | What it tells you | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Agent decision** | Approve or deny, as the agent judged it | | **Agent reason** | Why, in a line or two | | **Required changes** | The specific findings behind a denial, numbered — with how many the submitter has resolved, and any they dismissed as not applicable | | **Agent notes** | The agent's private aside to you. Reviewers only; never shown to the submitter | | **Deliverables** | Any files the stage produced, if it's configured to produce them | | **Agent transcript** | The agent's full message history, for when a verdict needs explaining | {% hint style="info" %} **The transcript is reviewers-only.** It opens with the prompt, which quotes your stage's private guidance — so it's restricted to the pipeline owner and stage owners, the same audience as the agent's raw output. {% endhint %} Earlier stages' reviews stay on the item, so you can see what's already been checked before you add your own view. If an earlier stage has **Pass findings to later stages** switched on, your agent was also given that stage's notes and files. Your agent is also handed whatever context came with the submission — the files, and any meetings or scopes of work the submitter attached — each under its own heading and labelled with the revision it arrived in, so new context is distinguishable from what you've already seen. Meetings and scopes are re-read from their source before the run, and one that has moved since it was attached says so in the label. See [Submitting & Revising Items](/build/pipelines/submitting-items.md). ## When an Item Comes Back A resubmitted item isn't reviewed from scratch. Your agent is handed the changes it asked for last time and answers each one — made, or not made — and the outcome follows from those answers rather than from a fresh opinion: * **Every change was made** → the item passes your stage. The agent doesn't get to deny on a new concern it thought of this round. * **Any change wasn't made** → the item goes back for exactly those changes, worded as you first asked for them. Nothing new is added to the list. The Review tab shows each change with a tick or a cross and the agent's own words about it, so a submitter can see what was accepted and what still isn't. {% hint style="info" %} **Why re-reviews are narrowed.** Review is open-ended by nature, and an agent asked "is this good?" a second time will usually find something else to want. Without this, a submitter who did everything asked of them gets a new list instead of a decision. Anything the agent notices but didn't ask for lands in **Agent notes** for you — you can act on it with your own authority, which is the part a submitter can't argue with. {% endhint %} **After three rounds the item comes to you.** If a stage has sent the same item back three times, the fourth denial lands as **Awaiting owner** instead, with what the agent wanted still attached. At that point it's a disagreement rather than a review, and it needs a person to settle it. ### Moving a Returned Item On Yourself A returned item sits with its submitter, which means a stage can stall over a change that turned out not to matter. As the stage's **owner or delegated approver** you can move it on without waiting: open the item and use **Move to \** in the "You approve this stage" bar under the tabs. You're asked for a reason, which the submitter and the next stage both see. This is the same authority you already have to approve an item waiting on you, applied to one you've sent back. The returning review is left as it stands — it did deny the item, and the timeline records that you overrode it. {% hint style="info" %} **Submitters can dismiss changes.** Alongside ticking changes off, a submitter can mark one **Doesn't apply**. A dismissed change stays on the checklist struck through, with who dismissed it and why. What happens when the list is cleared that way is a stage setting, **When the submitter dismisses an ask**: * **I approve dismissals** (the default) — the item comes to you as **Awaiting owner** with the dismissed rows in front of you. **Approve** accepts them and moves the item on. **Return with feedback** reopens the dismissed changes, and the reason is pre-filled with them. * **Move on automatically** — the item goes to the next stage as soon as nothing is left open. Dismissals by you, a delegate, or the pipeline owner never wait for approval, since any of you could move the item on directly. {% endhint %} ## Making the Decision In **Agent recommends, I decide** mode the item waits on you as **Awaiting owner**: * **Approve** — the item moves to the next stage, or is approved outright if yours is the last * **Return with feedback** — the item goes back to the submitter with your reason. The reason is pre-filled from the findings that are still open, so you can send it as-is or say it your own way Whatever you write is stored as the decision reason and is read back to the agent on the next attempt, so the findings reach it verbatim. In **Agent decides** mode the verdict moves the item on its own and you'll see it as already decided. You still get the full record, and as a stage owner you can change the mode at any time. {% hint style="warning" %} **You can override your agent.** An approval recommendation can be returned and a denial can be approved — the agent's verdict is advice, and the decision is recorded as yours. The **pipeline owner** can also decide at any stage, which is how an item gets unstuck when its stage owner is unavailable. {% endhint %} ### When a Stage Has More Than One Approver A stage can name **additional approvers** beside its owner. Any of them can make the decision, and all of them are notified when an item arrives — so a stage doesn't stall because one person is away. Items at those stages appear in your **Needs your decision** queue exactly as they would for an owner. The agent still runs as the stage **owner**, with the owner's integrations, whoever ends up deciding. See [Building a Pipeline](/build/pipelines/building-a-pipeline.md). ## When the Agent Errors If a review fails — a tool was unavailable, the agent hit an error — the item still lands on you rather than disappearing, and the failure is shown for what it is. Use **Re-run the agent** to try again. Re-running is also available while a review is queued or still running, for a review that's clearly gone astray. Each attempt is kept, so the record of what the agent said and when it broke stays intact. ## Notifications | Event | Who is notified | | ------------------------------------- | --------------------------------------------------------- | | **An item arrives at a stage** | That stage's owner | | **An item is resubmitted to a stage** | That stage's owner | | **A decision is needed** | The stage owner, once the agent has answered (or errored) | | **An item is returned** | The submitter, with the required changes | | **An item is approved** | The submitter | A returned-item notification carries the reviewer's reason and the required changes, so the submitter can start work from the email itself. Every notification links straight to the item. Delivery is controlled per person under **Pipeline activity** in your notification settings, with **Email** and **Push** as separate switches. See [User Configuration](/settings-and-configuration/user-configuration.md). ## A Few Habits That Help | Practice | Why | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Put the bar in Requirements, the nuance in guidance** | Submitters can act on requirements; guidance is where you tell the agent what you don't want to say out loud | | **Start in "Agent recommends, I decide"** | Watch a handful of verdicts at your stage before letting the agent decide alone | | **Fix the stage, not the item** | A finding the agent keeps missing is a requirements problem — edit the stage and it applies to every future submission | | **Read the findings before the reason** | The numbered findings are what the submitter will actually work from | | **Sort by Longest waiting** | The item that's been sitting is usually the one costing someone else time | ## Next Steps | Goal | Documentation | | ----------------------------------- | ---------------------------------------------------------------------------- | | Change what your stage asks for | [Building a Pipeline](/build/pipelines/building-a-pipeline.md) | | See what the submitter sees | [Submitting & Revising Items](/build/pipelines/submitting-items.md) | | Have your stage produce a document | [Deliverables & Completion](/build/pipelines/deliverables-and-completion.md) | | Ask Darcy where an item stands | [Pipelines with Darcy](/build/pipelines/pipelines-with-darcy.md) | | Tune the agent doing your reviewing | [Agents](/core-features/agents.md) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.darcyiq.com/build/pipelines/reviewing-and-deciding.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.