org-enhanced-priorities

org-enhanced-priorities enhances Org-mode’s default priority-based ranking with impact and difficulty. This extra information introduces more nuanced and fine-level control over agenda sorting, allowing you to confidently take the next task from the top of the agenda without wasting time thinking about it.

Installation

org-enhanced-priorities is not yet available via ELPA or other archives, so you must point use-package at this repo:

(use-package org-enhanced-priorities
  :straight (org-enhanced-priorities
             :type git
             :host github
             :repo "Robert-Forrest/org-enhanced-priorities")
  :init
  (require 'org-enhanced-priorities))

or manually install and add to your load path:

(add-to-list 'load-path "/path/to/org-enhanced-priorities")
(require 'org-enhanced-priorities)

Usage

org-enhanced-priorities calculates the overall priority of an item using the built-in priority property, and the additional properties of impact and difficulty.

Impact is thought of as “how much positive change will this task create?”, difficulty as “how hard is this task?”, and priority takes its usual meaning of “how urgent is this task?”. These properties are assumed to be on a scale of 1-3 (low-high).

The overall priority is the sum of these values after they have been multiplied by their respective weighting coefficients. The default values are currently:

Property	Weighting
Priority	7.5
Impact	2
Difficulty	-1
Deadline	4
Scheduled	4

Difficulty is negatively weighted such that harder tasks are ranked below easier ones. DEADLINE and SCHEDULED properties are taken into account such that priority increases as deadline dates approach, while priority is decreased until the scheduled date arrives.

These values can be customised to create whatever ranking system works best for you, via the variable org-enhanced-priorities-property-weights, an association list of property names and their respective weights. Simply add new key-value pairs to org-enhanced-priorities-property-weights to include other properties into the overall priority calculation:

(add-to-list 'org-enhanced-priorities-property-weights '("fun" . 10))

The contribution made by the vanilla org-mode priority labels (e.g. [#A]) to the overall priority calculated by this package is determined by normalising the char value between org-lowest-priority and org-highest-priority, such that it is agnostic to the labelling you have configured as long as it is in accordance with org-mode’s expectations of numerical ordering.

Example Org entry

The properties :impact: and :difficulty: have been added to this Org item.

* TODO [#A] High-priority Low-impact Medium-difficulty
:PROPERTIES:
:impact: 1
:difficulty: 2
:END:

Evaluating the following function while the cursor is over the above item would return 7.5 (assuming the default weights):

(org-enhanced-priorities--calculate-overall-priority)

See the examples directory for further exemplary org entries. When the agenda for the examples tasks is sorted using org-enhanced-priorities, the result is the following:

Open highest-priority task

Use M-x org-enhanced-priorities--highest-priority to open the org entry which currently has the highest priority among all entries in your agenda files. You may optionally set a match expression, this defaults to /TODO to only consider pending tasks, but you could enter /HOLD or any other valid match expression consumable by org-map-entries.

View all tasks, sorted by priority

Use M-x org-enhanced-priorities--sorted-entries to open a temporary buffer listing all org entries in order of the enhanced priority value. Similar to the agenda view, pressing RET on any entry headline will take you to the entry itself, while q will quit the buffer.

Agenda

Add the sorting function provided by org-enhanced-priorities to your agenda configuration:

(org-agenda-cmp-user-defined 'org-enhanced-priorities--agenda-sort-overall-priority)
(org-agenda-sorting-strategy '(user-defined-down))

I would highly recommend checking out the org-super-agenda package for further control over the appearance of the agenda.

Capture templates

You may find it useful to add the :impact: and :difficulty: properties to your task capture templates, so you can easily fill in the values:

(setq org-capture-templates `(("t"
                               "Task"
                               entry (file+headline "/path/to/tasks.org" "Tasks"),
                               "* TODO [#B] %? %^G 
:PROPERTIES:
:impact: 2 
:difficulty: 2
:END:"       
             :empty-lines 1)))

Future features

• [X] Arbitrary properties to be included in the ranking process, users should be able to define their own properties.
• [X] Better handling of currently hard-coded PRIORITY property translation from A, B, or C to a number, allow for other letters and numerical values.
• [X] Deadlines and scheduling should have an effect on the rankings. Priority should increase as deadlines approach, and should be zero before the scheduled start-date of a task.
• [X] A command which returns the highest priority task, to be done next.
• [ ] Availability of this package via an archive such as ELPA or MELPA.

Development

Contributions are welcome and desired, as well as any feedback or suggestions.

License

Please refer to the LICENSE file.