Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
This commit is contained in:
171
docs/guide/guided-review.md
Normal file
171
docs/guide/guided-review.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
title: "Guided Review"
|
||||
summary: "Read a change chapter by chapter, comment for the agent, and finish with a commit, fixes or a pull request."
|
||||
order: 6
|
||||
group: "Using Luxe"
|
||||
---
|
||||
|
||||
Guided Review reads a change back to you in the order it makes sense, split into chapters. Each
|
||||
chapter says what changed, why, and how it was checked, beside the code. Comments you leave go to
|
||||
the agent as work to do.
|
||||
|
||||

|
||||
|
||||
## Open a review
|
||||
|
||||
Press `ctrl+g`, or run `/diff`. Luxe writes the guide first; when `review ready` shows above the
|
||||
composer, press `ctrl+g` again to open it. Asked for while a turn is running, the review waits for
|
||||
the turn to end. A review you already have opens at once, and one you had open when Luxe stopped
|
||||
comes back with your comments.
|
||||
|
||||
| Review | Command |
|
||||
| --- | --- |
|
||||
| Uncommitted changes | `/diff` |
|
||||
| What the last turn changed | `/diff turn` |
|
||||
| Everything since a branch or commit | `/diff base main` |
|
||||
| One commit | `/diff commit 4c1e2a0` |
|
||||
| A pull request | `/diff pr 142`, `/diff pr #142`, or its address |
|
||||
|
||||
Inside a review, `s` changes what it covers: uncommitted changes, the last turn, a base or a commit.
|
||||
A pull request takes `/diff pr`. If the agent committed its work, so nothing is uncommitted,
|
||||
`ctrl+g` and `/diff` review the last turn instead. Luxe remembers what you have already reviewed in
|
||||
each project, so the next review leads with what is new since then.
|
||||
|
||||
## Read it
|
||||
|
||||
The guide on the left opens with why the change exists and what it does, then a block per chapter
|
||||
with its files. The right pane shows the hunk you are on, with the guide's sentence about it. Drag
|
||||
the line between them to give the guide more or less room; double-click it to go back.
|
||||
|
||||
| To | Key |
|
||||
| --- | --- |
|
||||
| Next step. Past the last one, finish. | `space` or `n` |
|
||||
| Previous step | `shift+n` |
|
||||
| Next or previous chapter | `]` / `[` |
|
||||
| Next or previous file | `ctrl+↓` / `ctrl+↑` |
|
||||
| Scroll | `↑` / `↓`, `pageup` / `pagedown`, or half a page with `ctrl+d` / `ctrl+u` |
|
||||
| Hide the guide, or the hunk's sentence | `g` / `z` |
|
||||
| Side by side, or one column | `ctrl+b` |
|
||||
| Wrap long lines | `w` |
|
||||
| Search | `/` |
|
||||
| Every key in the review | `?` |
|
||||
| Back to the conversation | `esc`. The review stays pinned until you return. |
|
||||
|
||||
### What needs you
|
||||
|
||||
A review lists the hunks that need your attention and accounts for the rest. A hunk covered by a
|
||||
test that passed says so on its own header and stays in the diff. Lockfiles, generated files,
|
||||
moves and formatting-only changes fold away, each run of them in a file into one row; `f` opens
|
||||
them all.
|
||||
|
||||
Three things are flagged and stay on the list, whatever else passed. Each flagged file says so on
|
||||
its row and in the walkthrough, and the guide gives the total for any kind with more than two:
|
||||
|
||||
- A line that looks like a credential (`sk-…`, `ghp_…`, `AKIA…`, a `password = "…"`)
|
||||
- A weakened check: a deleted test, an added `#[ignore]`, an edit to CI or `deny.toml`
|
||||
- A file the agent edited without reading first
|
||||
|
||||
If a test fixture needs a value that looks like a credential, mark that line with
|
||||
`// luxe:allow-secret`, `gitleaks:allow`, `pragma: allowlist secret` or `nosec`.
|
||||
|
||||
To leave project bookkeeping out of every review:
|
||||
|
||||
```json title=".luxe/config.json"
|
||||
{ "review": { "exclude": ["PROGRESS.md", "docs/design/**"] } }
|
||||
```
|
||||
|
||||
The patterns take `*`, `**`, `?` and a trailing `/`, and a project's list replaces your own.
|
||||
Excluded files are counted in the guide. Luxe's own `.luxe/` is never reviewed.
|
||||
|
||||
A review leaves out a file it cannot hold, so the rest is still reviewable: in the last turn, any
|
||||
file over 1 MiB, unreadable, or not a regular file; in uncommitted changes or a base, a new file
|
||||
that is not ignored and is over 1 MiB or not a regular file. The top of the guide names each one,
|
||||
so a review that shows less than the change never passes for all of it.
|
||||
|
||||
## Comment and ask
|
||||
|
||||
| Key | Does |
|
||||
| --- | --- |
|
||||
| `c` | **Comment** on the line under the cursor. It waits for you to send it: to the agent, or to GitHub with your review of a pull request. |
|
||||
| `a` | **Ask the agent** about the line. It answers right away and changes nothing. |
|
||||
| `alt+c` | **Feedback**: every comment, with the one under the cursor in full |
|
||||
| `alt+u` | **Send** the unsent comments to the agent, from a preview where `space` leaves one out |
|
||||
|
||||
In **Feedback**, `enter` goes to a comment, `c` replies, `e` edits, `x` deletes one not yet sent,
|
||||
`r` marks it verified, resolved or reopened, `d` shows its details, `alt+r` moves a stale one to
|
||||
where its line went, `v` shows what changed at its line, and `u` sends. On an answered question, `c` turns it
|
||||
into a comment, so the question, the answer and your direction reach the agent together.
|
||||
|
||||
You can keep commenting while the agent works on what you sent. When the agent's fix is in, the
|
||||
review says `The fix is in · ctrl+r refresh`. `ctrl+r`, or `/diff refresh`, reads the code again
|
||||
so you can verify it, at any time.
|
||||
|
||||
The agent ends a fix by reporting on each comment: fixed, not fixed, or needs clarification, with a
|
||||
note. The note shows under the comment, and a comment it calls fixed waits for you to verify it,
|
||||
since a claim is not proof. If the agent leaves its report out, Luxe asks for it once. A comment
|
||||
the agent still says nothing about reads `no word from the agent`, with the reason in Feedback,
|
||||
and stays where you left it.
|
||||
|
||||
## Finish
|
||||
|
||||
`alt+enter` finishes the review:
|
||||
|
||||

|
||||
|
||||
| Choice | Does |
|
||||
| --- | --- |
|
||||
| **Accept** | Mark it reviewed. The agent is not told. |
|
||||
| **Accept and commit** | Accept, then commit each chapter as its own commit, with the chapter's explanation as the message. Never pushes. |
|
||||
| **Request fixes** | Send your comments for the agent to address |
|
||||
| **Comment only** | Send your comments without asking for edits |
|
||||
| **Keep reviewing** | Close this and carry on. Nothing is sent. |
|
||||
| **Open pull request** | Commit, push and open a pull request drafted from the review. Offered when the branch has none. See [Git and GitHub](github.md#open-a-pull-request). |
|
||||
| **Open as a stack** | One pull request per chapter. Offered with two chapters or more. |
|
||||
| **Answer on GitHub** | On your own pull request: reply to and resolve the threads you fixed |
|
||||
|
||||
**Accept and commit** shows the commits first; `s` there makes them one. A review of a base or a
|
||||
commit can only be committed that way. It refuses if files are already staged or the code changed
|
||||
after the review was captured.
|
||||
|
||||
## Review a pull request
|
||||
|
||||
`/diff pr 142` reads a pull request into the same review: a teammate's, a bot's, or one another
|
||||
agent opened. It needs the GitHub CLI, `gh`, signed in.
|
||||
|
||||

|
||||
|
||||
- It is pinned to the commit GitHub reported and compared from where it branched, as GitHub's
|
||||
**Files changed** does. Nothing in your checkout moves.
|
||||
- The head says who opened it and where it stands: `by dependabot (bot) · 1 failing · changes requested`.
|
||||
- The author's description follows the guide, under its own heading.
|
||||
- Review threads appear under the lines they are about. Anything without a line is under
|
||||
**Discussion on GitHub**.
|
||||
- `a` asks the agent about a line, at the pull request's commit.
|
||||
- `ctrl+r` reads it again after a new push.
|
||||
|
||||
### Post your review
|
||||
|
||||
`alt+enter` on a pull request shows exactly what will be posted before anything is:
|
||||
|
||||
| Key | Does |
|
||||
| --- | --- |
|
||||
| `tab` / `shift+tab` | Choose **Comment**, **Approve** or **Request changes** |
|
||||
| `c` | Write the summary. **Request changes** needs one. |
|
||||
| `d` | Have the agent draft the summary from this review |
|
||||
| `e` | Edit the summary |
|
||||
| `enter` | Post it |
|
||||
|
||||
Line comments are listed under their files with the diff they sit on, the way GitHub shows them.
|
||||
Questions you asked the agent stay in Luxe and are never posted. On your own pull request, GitHub
|
||||
only takes a comment, so that is all Luxe offers.
|
||||
|
||||
A drafted summary opens in the preview for you to read and edit. Anything the agent says beside it,
|
||||
such as a part of the change it did not read, appears under it as a note. Once the review is
|
||||
posted, the guide's foot says **Posted to GitHub** with the verdict, and `o` opens it.
|
||||
|
||||
### Fix it yourself
|
||||
|
||||
To change someone else's pull request rather than comment on it, press `alt+u` (or `w` in the post
|
||||
preview). Luxe asks GitHub whether you can push to it, then checks it out in a worktree of its own
|
||||
and starts a session there, with your comments as the agent's first task. A plain `git push` then
|
||||
updates the pull request.
|
||||
Reference in New Issue
Block a user