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
ctrl+_	Hide the hint rows, or show them again

Typing filters. That is why deleting, resuming and the hint toggle are on ctrl+d, ctrl+r and ctrl+_ 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
ctrl+_	Hide the hint rows, or show them again
?	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, and opens whatever hides the note it is going to — a folded section, or an unchanged run in a diff.

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.

Putting it away

The bar says how to put itself away, on its own second-to-last entry — ? help stays the last word of the line:

… s submit · esc back · ctrl+c exit · ctrl+_ hide hints · ? help

ctrl+_ hides every hint row at once — on a narrow terminal the bar wraps to as many as three, and all of them go together. The way back is written on the bottom border, on the left, and that is the only thing that border ever gains:

╰─ ctrl+_ show hints ──────────────── Star github.com/thisisnsh/planx ─╯

While the bar is up the border says nothing, because the bar already says it.

The rows go to whatever the bar was sitting under: more plan in a review, more rows in the picker. The choice is remembered in ~/.planx/config.json and holds across all three screens — the review, the picker and planx defaults — until you press it again.

Three bars are drawn whatever the flag says, because in each of them the bar is not hints:

• An armed ctrl+c. Press ctrl+c again to exit. takes the hint bar rather than a row of its own, so hiding it would make the first press look like it did nothing.
• The picker's delete confirmation. The bar is the gate's own enter delete / esc cancel.
• The review's ? screen. The bar says any key to close, and the press that would toggle is a key — so it closes the screen. One press, one effect.

If your terminal sends nothing for ctrl+_, see Troubleshooting.

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.