org.nvim

Weekly review (GTD)

Stability: experimental (org-extensions-stability)

review walks you through a GTD weekly review, one step at a time, in a floating window:

require("org").setup({ extensions = { review = {} } })

:Org review (action review, global key <prefix>W) starts the review, or resumes the one you left. The header shows the progress (a dot per step) and the step's title; the footer lists the keys. The default steps:

inboxEmpty the inbox: the top-level entries of inbox (default default_notes_file), to refile, schedule, give a TODO state, delete or skip one by one
stuckStuck projects, as the agenda finds them (agenda.stuck_projects, org-agenda)
waitingEntries in a waiting_keywords state (WAITING)
overdueOpen entries scheduled or due before today, oldest first
upcomingScheduled, due and dated entries of the next upcoming_days (14) days, repeaters included, in date order
somedayEntries tagged or in a state of someday (:someday:, :maybe:, SOMEDAY, MAYBE)
clockThe time clocked in the last clock_days (7) days, and the clock_top (10) entries it went to
reflectQuestions (questions) answered in a note buffer

:Org review <step> jumps to a step by name or number (<Tab> completes the names), and :Org review restart drops an unfinished review and starts over.

Keys in the review window

n ]]next step (review_next)
p [[previous step (review_prev)
<CR>go to the entry (the review is paused), or answer the question under the cursor
rrefile the entry (org-refile)
s Sschedule it / set a deadline (the date prompt)
tset its TODO state from a list
ddelete it (asks first, confirm_delete)
xskip it: it is marked and the cursor moves on
ianswer the question under the cursor
Rrefresh (collect the step's entries again)
Ffinish (review_finish)
<Esc> qpause (review_quit)

Change them with keys (a key, a list, or false for none).

The entries are read from the agenda files, and every change is saved to its file right away. An entry is found again by a mark in its buffer, its ID, its line or, failing those, as the only entry with its title, level and outline path: when two entries could be meant, nothing is done and R lists them again. The entries of a builtin step are collected again only when an agenda file changed (or R). The progress (the step, the answers, what was skipped and the counts) is kept in state_file, so closing the window, going to an entry with <CR> or quitting Neovim pauses the review and :Org review picks it up again.

Finishing

F writes a review entry into a date tree of log_file (default "review.org" in org_directory; a week tree, log_tree_type): the time, what was done with the inbox, how many entries each step listed, the time clocked, and each answer under its question as a subheading. The text is indented for the entry's level when adapt_indentation is on, and an answer line starting with * gets a leading space so it can't become a headline. A new log file starts with its date tree, without the empty first line an Emacs date tree leaves. With capture_template set to a template key, the review is captured with that template instead, the summary being its initial text (%i), so it can be edited before it is stored. The saved progress is forgotten once the entry is stored; if it can't be stored, :Org review picks the review up again. A missing directory of log_file is created.

Custom steps

steps lists the steps in order. An entry is a builtin name, a builtin with overrides ({ "waiting", title = "Blocked" }), a function returning the items of a new step, or a table:

steps = {
  "inbox",
  {
    name = "reading",
    title = "Reading list",
    description = "Anything worth reading next week?",
    items = function(ctx)
      local ql = require("org.extensions.ql")
      return ql.select(ctx.files, '(tags "read")', {
        action = function(hl)
          return { hl = hl, path = hl.file.filename, lnum = hl.line }
        end,
      })
    end,
    keys = { a = function(item, session) end },
  },
  "reflect",
}

items(ctx) returns { hl, path, lnum, info? } entries (info is shown after the title) or { text = "..." } lines; lines(ctx) adds text above them; keys are mapped while the step is shown. ctx has opts, today, now, files (the agenda files) and state.

Options

stepsthe steps (see above)
inboxinbox file(s) (nil: default_notes_file)
waiting_keywords{ "WAITING" }
someday{ tags = { "someday", "maybe" }, keywords = { "SOMEDAY", "MAYBE" } }
upcoming_daysdays of the "upcoming" step (14)
clock_daysdays summed by the "clock" step (7)
clock_topentries listed by the "clock" step (10)
questionsthe questions of the "reflect" step
log_filethe review log (nil: "review.org" in org_directory)
log_tree_type"day", "week" (default) or "month"
log_headingheading of the logged review ("Weekly review")
capture_templatefinish with this capture template (nil)
open_logshow the new log entry after finishing (true)
confirm_deleteask before deleting an entry (true)
state_filethe saved progress (stdpath("data")/org/review.json)
width heightsize of the window (96 x 30, clamped to the screen)
borderits border ("rounded")
keyskeys in the window (see above)