Handling TODO items with "pain lists"
=======================================
The 'painlist' program reads items (tasks/bugs/issues/...) on stdin,
one per line, not indented. Items are arbitrary text, rated by
adding ">AxBxC<" anywhere on the line, where A,B,C,... are rating
numbers in arbitrary categories. Any number of categories can be
used.
If a non-option argument is given, it is interpreted as an extended
regular expression to filter for. The -v option inverts the filter.
Empty lines and those containing only a shell-style comment (#) are
ignored. In-line comments are not recognized; this allows the use
of hash-tags.
the rating scale is always 1-9; 9 should always be used for the
highest level. Coarser scales should be mapped to 1-9 by ignoring
some levels; for instance, use 1,3,5,7,9 for a 5-level scale. It
is recommended to document a clear meaning for each level to make
rating easy and unambiguous.
the value of a pain tag (">...<") is the geometric mean of the
ratings. An item can have multiple pain tags which are summed.
the output sorts items by pain value. A solid line visualizes a
configurable threshold (default -t 6). A dotted line shows the
weighted median (half of total pain). Higher-value items are shown
in a brighter shade.
EXTRA FEATURES
----------------
It is suggested to use the following features only in specific
circumstances as indicated.
- Text in square brackets [...] at the beginning of a line is
highlighted in the output. This can be used for example to mark
items with a planned time.
- Items can be marked for urgency after time T by adding a tag of
the form "!T" where T is given in (fractional) megaseconds after
the Unix epoch. Yes, it is awkward, but also simple. How to
convert using GNU date:
$ when() { echo $(($(date +%s -d "$1") / 1e6)); }
$ when tomorrow
1459.43703
(Hint: Round to the first decimal place, a day is 86.4ks.)
Urgent items are displayed in red. Use this feature to flag items
before it becomes too late to act on them.
- Items marked with a tag of the form "^T" will be ignored until
time T. Use this for items that cannot or should not be acted
on before the given time.
- Indented (non-comment) lines below an item are interpreted as
items pending completion of their parent. For each child, a green
plus sign is appended to the parent item. Pending items are not
shown themselves but count toward the pain value of their parent.
Use this to account for but otherwise hide items that strictly
depend on the completion of another.
REFERENCES
------------
Daniel Cook, "Improving Bug Triage with User Pain", 2008
https://lostgarden.home.blog/2008/05/20/improving-bug-triage-with-user-pain/
