README

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/