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:
| inbox | Empty 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 |
| stuck | Stuck projects, as the agenda finds them (agenda.stuck_projects, org-agenda) |
| waiting | Entries in a waiting_keywords state (WAITING) |
| overdue | Open entries scheduled or due before today, oldest first |
| upcoming | Scheduled, due and dated entries of the next upcoming_days (14) days, repeaters included, in date order |
| someday | Entries tagged or in a state of someday (:someday:, :maybe:, SOMEDAY, MAYBE) |
| clock | The time clocked in the last clock_days (7) days, and the clock_top (10) entries it went to |
| reflect | Questions (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 |
| r | refile the entry (org-refile) |
| s S | schedule it / set a deadline (the date prompt) |
| t | set its TODO state from a list |
| d | delete it (asks first, confirm_delete) |
| x | skip it: it is marked and the cursor moves on |
| i | answer the question under the cursor |
| R | refresh (collect the step's entries again) |
| F | finish (review_finish) |
| <Esc> q | pause (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
steps | the steps (see above) |
inbox | inbox file(s) (nil: default_notes_file) |
waiting_keywords | { "WAITING" } |
someday | { tags = { "someday", "maybe" }, keywords = { "SOMEDAY", "MAYBE" } } |
upcoming_days | days of the "upcoming" step (14) |
clock_days | days summed by the "clock" step (7) |
clock_top | entries listed by the "clock" step (10) |
questions | the questions of the "reflect" step |
log_file | the review log (nil: "review.org" in org_directory) |
log_tree_type | "day", "week" (default) or "month" |
log_heading | heading of the logged review ("Weekly review") |
capture_template | finish with this capture template (nil) |
open_log | show the new log entry after finishing (true) |
confirm_delete | ask before deleting an entry (true) |
state_file | the saved progress (stdpath("data")/org/review.json) |
width height | size of the window (96 x 30, clamped to the screen) |
border | its border ("rounded") |
keys | keys in the window (see above) |