Help CenterFeaturesPrototypes & accepting work
Prototypes & accepting work
Features

Prototypes & accepting work

What it is

A prototype is what the UI should look like: drawn first, and built only after you approve it. The finished work is compared against it. When you accept the work, you look at the prototype and what was built in side-by-side screenshots, and see at a glance whether they match.

Acceptance is when a session finishes and you take a look to see if it's right. If it is, click "Done", and the changes are merged into the main code. If not, click "Send back", say what's wrong, and the session keeps working on it.

When to use it

  • Changing the UI: prototype first, finalize, then build. Whether a UI is right is the hardest thing to put into words, and changing a prototype is much cheaper than changing code.
  • Work without a UI (backends, command-line tools, writing docs): no prototype needed. Build it and accept it directly.

First-time setup

Connect the prototype (Project settings › Prototype › Connect prototype): pick the folder the prototype is in. If the prototype needs building first, fill in a build command and approve it once. What you approve is the exact command and the scripts it calls directly; if the command or the scripts change, you're asked again.

Register the dev build (Project settings › Run & preview): register the start command that runs the project, like pnpm dev, and approve it once. Sessions need this to start a dev build and put screenshots side by side with the prototype; commands you haven't approved can't start. You can also have a session read the repo and draft it, and you just click "Approve".

Choose how requests flow (Project settings › Rules › How requests flow): see "Requests: several steps in a row" below.

How to use it

Looking at the prototype

Press ⌘\ to open the right panel.

  • Click a page in the page bar to switch to it. You can switch between states (like the empty state, or when there's an error) and switch to dark mode.
  • You can view it in the middle at its design size, or open it in a separate window.
  • Under Version you can see what's "committed" and the "Uncommitted changes". If a build breaks, the last successful one is still shown.
  • When the prototype is on another computer, that computer builds it and syncs it to this one. Even when that computer is offline, you can see the version already saved.

Changing the prototype

  1. In the lower half of the right panel, click "Start a prototype session". It opens in the prototype folder.
  2. Tell it what to change. What you send includes which page and which state you're looking at.
  3. To point at something: click "Pick element", then click the spot on the prototype you want changed, and it knows which part you mean.
  4. Its changes don't need committing. The right panel refreshes by itself within half a minute.

Finalizing

When you're happy with the changes, click "Finalize" below the prototype in the right panel. Only then does the prototype session commit this version. A finalized version says what time you finalized it.

The prototype session doesn't commit on its own after every turn, so the build always works from the version you finalized. The task says which version and which state of the prototype to build from. If the prototype changes later, you're told.

Requests: several steps in a row

Work that takes several steps in a row (like drawing a prototype first, then building it) is called a "request". In the left sidebar, the sessions of one request are grouped together, with "2 / 3 steps" on the right.

Each project chooses one way to flow (Project settings › Rules › How requests flow), and Q picks by it when creating a request. For a single request, just tell Q to switch:

FlowGood for
Depends on the prototypePrototype first if there is one, otherwise build directly (most projects choose this)
Prototype firstPrototype → build → prototype session checks → you accept
Build → reviewBackend or command-line projects without a UI
Research onlyNo code changes; you get a written conclusion

The same page has two "Who checks for you" options. When one is off, you're asked at that step:

  • Finalize once Q has checked: if the prototype matches what you originally said, it's finalized and handed to the session that will build it. Anything you didn't say originally, you're still asked about.
  • The prototype session checks the UI for you: when a session finishes, it first goes to the prototype session to check against the prototype. If it doesn't match, it goes back for changes, up to 2 rounds; if it still doesn't match, it comes to you to decide.

When every step is done, "Needs you" gets an item saying "the whole request is done". You can accept it all together, or open each one to look.

Accepting work

Open the task in "Waiting on you". The top of it is the acceptance view:

  • Screenshots of the prototype and what was built, side by side (projects without a UI have no screenshots). Click to fill the window: side by side, top and bottom, or one side only. ⌘ plus the scroll wheel zooms, and ← → switches sides.
  • Tests, acceptance criteria and how much changed, in one line.
  • If Q looked first, Q's suggestion is shown there too.
  • Below are "Done / Send back / Open session".

When you send back, write one sentence about what's wrong. You can paste screenshots right in, and the session keeps working on it. You can also just tell Q: "Send QS-13 back, the button should be at the bottom right." (QS-13 is the task number.)

The system already blocks these for you, so you don't have to worry about them:

  • Work with failing tests or a merge conflict doesn't count as done. The task stays in "Waiting on you" with the reason written down.
  • Before a session hands in its work, QU tries merging its changes once (not for real, just to see whether they fit). If they don't, the session sorts it out on the spot.
  • If several tasks not yet merged would clash with each other, the sessions in charge are told ahead of time.
  • If a docs task changed code, it's flagged and can't be accepted directly.

Tasks Q suggests accepting can be accepted together in "Needs you".

Q accepts (off by default)

You can let QU accept small changes for you and merge them in. Turn it on under "Project settings › Q accepts", and choose which task types. It only accepts for you when all of these hold:

  • There's at least one acceptance criterion, and all are ticked;
  • All tests passed after the last code change (if there's a PR, CI passed too);
  • If a plan needed your approval, you approved it;
  • The change is small: no more than 5 files and 150 lines (generated files and test files don't count);
  • Q has looked at it and suggests accepting.

Changes to the UI, deploys or databases still wait for you by default; each has to be ticked separately to open it up. Client projects, and changes to dependencies, deleted files, changed images or fonts, or changed CI config, always wait for you. It accepts up to 10 a day. You can undo any of them at any time (anything already merged isn't undone automatically).

FAQ

Can I use QU without a prototype? Yes. Work without a UI is built and accepted directly. When accepting, there are no side-by-side screenshots; you look at the tests, acceptance criteria and changes.

Do I have to compare screenshots one by one when accepting? No. The session has already taken the side-by-side screenshots; a glance is enough. To look closely, click to enlarge.

How is a prototype session different from a normal session? A prototype session opens in the prototype folder and only changes the prototype. It only commits when you click "Finalize".