Concepts

The review loop

1. You ask the agent for some work and for the checks, in the chat.
2. The agent writes checks: one thing to test per item, with what should happen.
3. You test and mark each item on any of your devices, with notes where useful.
4. You tell the agent in the chat that you are done. There is no “done” button in the app: the agent only reads the review when you ask it to.
5. The agent reads the review with palmtop feedback, fixes what doesn’t work, answers your questions and asks you to check again.

Projects

A project is a folder on your computer: the root of the git repository, or the current folder outside git. It is created the first time an agent starts a session in that folder.

You pair a device with a computer, once, and it sees every project of that computer, including the ones started later. On your devices a project is shown as COMPUTER - project, for example MacBook - my-app, and the project list is sorted by what happened last.

Sessions

The agent starts a session for each conversation (palmtop session start), with a short title. Two agents working in the same project at the same time have separate sessions. The app follows the work: it shows the project and the session with the latest activity, wherever your agent is working. Pick a project or a session from a list and it stops following until you turn Follow activity back on.

Sessions stay until you delete them, from any device (session menu, Delete session…) or with palmtop sessions delete. Deleting removes its checklists and reviews everywhere.

Checklists and checks

A session holds one or more checklists; each item is a check, something for you to verify. The agent writes them for a small screen: short, one check per item, with the expected result.

Review statuses

The mark says whether a check works. The note, when you write one, tells the agent what to do.

✓ It works (done in the CLI)

• No note, or a confirmation like “ok”: nothing to do.
• A change or an extra, like “dim the button while loading”: the agent does it.
• A partial problem, like “works, but no notification arrives”: the agent fixes that part.

✕ It doesn’t work (cancelled in the CLI)

• A note saying what happens, why it fails or how to fix it: the agent uses it to fix the problem.
• A partial result: the agent fixes the part that doesn’t work.
• “Remove this feature”, even if it works: the agent removes it.
• “Not tested”: counts as not reviewed.
• No note: the agent asks you what happened before changing code.

? Question (question in the CLI)

• No note: you want more information, for example you didn’t understand the check. The agent explains it.
• With a note: the agent answers it.
• The agent doesn’t change code for a question, unless the note asks it to.

No mark: not tested yet. Never treated as passed.

After a fix the agent asks you to check the item again. Tap the chosen mark again to clear it. If the agent changes the text of a reviewed item, the review is cleared: you check the new text again.

Notes and messages

• Note on a check: what went wrong, or your question.
• Note for the agent: one per session, at the bottom of the session, about the whole work. The agent reads it with the next feedback.
• Items you add: + Add item at the bottom of a checklist. The agent reads them as requests: something more to verify or fix.
• Message from the agent: a short, read-only status at the top of the session, for example “Login fixed: 4 checks for you”.

Feedback

palmtop feedback shows the agent what changed since it last read: new or changed reviews, items you added, your note for the agent when it is new, and the items still to review. Each review is reported once, unless you change it.