Hi.  I've been using Emacs since the 80's but I'm a new org mode user.
What a fantastic piece of software.  I had used my own todo mode, but org
is orders of magnitude better. Thank you!

My main todo file defines various TODO keywords and initial state like this:

#+STARTUP: indent overview
#+TODO: @NOW @NEXT @WIP @PENDING

What I really want is to initially only see items noted with those TODO
keywords and also due items.  Everything else should be hidden.

Since I didn't see an out-of-the-box way to do this, I hacked the following
together.  The purpose of this email is to see if this is the right way (or
a good way).

The hack starts with this at the end of the org file:

* Local Variables
;; Local Variables:
;; eval: (save-window-excursion (my-org-show-sparse-todo-tree))
;; End:

That function is defined thus:

(defun my-org-show-sparse-todo-tree ()
  (interactive)
  (message
   "%d TODO entries found"
   (org-occur (concat "^" org-outline-regexp " *"
     "\\("
     (mapconcat 'identity org-todo-keywords-1 "\\|")
     "\\)\\>")))

  ;; events due before 2 weeks from now:
  (org-check-before-date
   (format-time-string "%Y-%m-%d" (time-add nil (* 3600 8 14)))
   t))

which relies on the redefined version of org-check-before-date, so
keep-previous is passed to org-occur:

(defun org-check-before-date (d &optional keep-previous)
  "Check if there are deadlines or scheduled entries before date D.

Optional argument KEEP-PREVIOUS is passed directly to `org-occur'."
  (interactive (list (org-read-date)))
  (let* ((case-fold-search nil)
(regexp (org-re-timestamp org-ts-type))
(ts-type org-ts-type)
(callback
 (lambda ()
   (let ((match (match-string 1)))
     (and (if (memq ts-type '(active inactive all))
      (eq (org-element-type (save-excursion
      (backward-char)
      (org-element-context)))
  'timestamp)
    (org-at-planning-p))
  (time-less-p
   (org-time-string-to-time match)
   (org-time-string-to-time d)))))))
    (message "%d entries before %s"
    (org-occur regexp keep-previous callback)
    d)))

I find this shows me exactly what I want to see when I finish a task and
want to start something new.

If this is the right way and the maintainer wants me to submit a patch, I
would include these functions to get a new optional for keep-previous,
since they could all plausibly be used for the same thing that
org-check-before-date was:
* org-show-todo-tree
* org-check-deadlines
* org-check-before-date
* org-check-after-date
* org-check-dates-range

Thank you.

Kevin