Reviewing

Reviewing

The review is a terminal interface over one stored version. You read it, fold what you do not need, select the lines that are wrong, say what is wrong with them, and submit.

Opening one

planx                     # the picker: every plan PlanX has stored
planx <plan-id>           # that plan, at its latest version
planx <plan-id> v<n>      # that exact version

diff in front of a plan is optional — planx <id> and planx diff <id> are the same command.

Opening a version that has one shows its diff against the previous version first: you opened v4 because v4 is new, and what is new about it is the diff. Press d for the plan on its own. See Versions and diffs.

The picker

Run planx with no arguments and you get a list of every stored plan, newest first, each opening into its own versions.

Plans are grouped by where they were captured:

• This directory — plans captured from the directory you are standing in.
• Elsewhere — everything else, folded shut when the first group has anything in it. With nothing captured here, the second group is the list and opens as one.

A version row that was executed is tagged executed and painted green. So is its plan row, until the plan gains a newer version than the one that was built — what was executed is no longer the plan, and the green stays on the child row, which is where the history is.

Picker keys

Key	What it does
↑ ↓	Move the cursor. ctrl+p and ctrl+n do the same
→	Open the nearest thing that is shut: a section, then a plan's versions
←	Shut the nearest thing that is open: a plan's versions, then its section
enter	Open the row. On a folded header, open the section
ctrl+d	Delete the plan or version under the cursor, after a confirmation
ctrl+r	Resume the session that built this version
type anything	Filter the list. backspace edits the query
ctrl+c	Leave PlanX — twice

Typing filters. That is why deleting and resuming are on ctrl+d and ctrl+r rather than bare letters: a bare d would open a confirmation before the filter ever saw it, and no plan whose name starts with d could be searched for. A filtered list matches plans only and draws every one collapsed, so neither arrow does anything while a query is live.

esc does not leave the picker. Leaving PlanX is ctrl+c twice, wherever you are. Inside the delete confirmation esc still means not this row, which is backing out of a question rather than leaving.

ctrl+d has no undo behind it. The red confirmation names its target in full because it is the only thing between the keystroke and a plan that is gone. The latest version of a plan never offers a delete — it is the plan.

ctrl+r is not on every row. A version offers it when there is an execution session recorded behind it. A plan row offers it only where exactly one of its versions qualifies, because picking silently between two builds is worse than making you press → first.

The review screen

The plan is drawn as rendered markdown with a cursor on it. Everything happens from that cursor: a section folds where you are standing, a selection starts where you are standing, feedback attaches to what you selected.

Every key

Press ? in a review for this list on screen.

Key	What it does
← →	The previous and next version of the plan
↑ ↓	A row at a time — held, 2 rows after 1.5s and 5 after 4s
d	Show the diff against the previous version, or hide it
e	Edit the line, or every line of the selection, in place
f	Add feedback on the selection, or edit the note under the cursor
g G	The top and the bottom of the plan
ctrl+j ctrl+k	A whole screen down or up
h	Fold or unfold every note at once
j	The next feedback on this version, wrapping at the end
n	Add or edit the note about the whole plan
s	Submit everything at once, then pick what happens to the plan next
space	Collapse the section you are in, or the note — or expand what is hidden
v	Start or end a selection, then ↑ ↓ to extend
esc	Back to the list
?	This list
ctrl+c	Leave PlanX — twice

← → and d are only there on a plan that has more than one version.

Inside a note or a line you are editing

Key	What it does
← →	Move the caret one character
⌥← ⌥→	Move the caret one word
ctrl+a ctrl+e	The start and the end of the text
enter	Save it

A note box is one stop for the cursor, on its first line of text.

A note is deleted by emptying it: f, clear the text, enter. There is no separate delete key, and an empty note is not a note.

Reading a long plan

space collapses the section you are standing in, the note under the cursor, or an unchanged run in a diff — and expands whatever is hidden there. A ## folds and takes its subsections with it; a #### folds on its own.

h folds every note at once, for a pass over the plan itself after a round of commenting. j walks the feedback on this version, wrapping at the end.

g and G reach the ends, and ctrl+j / ctrl+k move a screen at a time. The arrows accelerate when held, so a plan of two hundred rows is not two hundred presses.

The hint bar

The bar along the bottom shows only what works on the row you are on. d reads show diff or hide diff depending on which you are looking at; a row with no versions behind it offers neither arrow. ? is pinned last, because it is the key that recovers whatever the width dropped.

Submitting

s submits your line comments, your direct edits and your plan-wide note together, then asks what happens to the plan next. See Feedback and edits and Hand-offs.

Submitting with nothing on the plan is meaningful: it says the version was reviewed with nothing to change. PlanX does not create an identical revision for it — that version is ready to build.