This is org-gtd.info, produced by makeinfo version 7.2 from
org-gtd.texi.

Copyright (C) 2018-2026 Aldric Giacomoni <trevoke@gmail.com>

   You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.

   This document is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Org GTD: (org-gtd).   An opinionated GTD flow implemented in org-mode.
END-INFO-DIR-ENTRY


File: org-gtd.info,  Node: Top,  Next: Summary,  Up: (dir)

Org GTD User Manual
*******************

Org GTD is an attempt to implement the GTD flow described in the GTD
book as faithfully as possible.

This manual is for Org GTD version 4.0.0

* Menu:

* Summary::                      quick intro to GTD

-- The Detailed Node Listing --

Summary

* What's new in 4.0: What's new in 40.
* Setting up Org GTD::
* Getting Started with Org GTD:: Tutorials to get you productive quickly
* Using Org GTD::                How Org GTD maps to the GTD flow
* Reference::                    Complete reference for all org-gtd features
* Extending org-gtd::
* Troubleshooting::

What's new in 4.0

* Flexible project dependencies (the big one!)::
* Simplified keyword configuration::
* Data-driven configuration::
* Declarative view language::
* Better project modification::
* Updated terminology Review → Reflect::
* Updated terminology Incubate → Tickler + Someday/Maybe::
* Enhanced reflect capabilities::
* Simplified configuration::
* Per-type refile prompting::
* Capture timestamps::
* What you need to do::
* Previous versions::


Setting up Org GTD

* Upgrading::                    How to upgrade your local setup across major versions
* Installing::                   Get Org GTD in your emacs
* Configuring::                  Required and optional system configuration


Getting Started with Org GTD

* Quick Start Reference::
* Tutorial Your First Project::
* Tutorial Creating Your First Custom View::
* Tutorial Quick Wins and Focus Work Views::


Using Org GTD

* Your Daily Workflow::          The GTD cycle you'll practice every day
* The GTD Flow in Depth::        Detailed explanation of each GTD step
* Understanding GTD Item Types:: When to use each type in the organize menu
* Working with Projects (Advanced)::
* Automating through emacs::


Reference

* Configuration Variables Reference:: All customization variables explained
* Commands Reference::           All interactive commands explained
* Properties Reference (Internal Implementation):: All org properties used by org-gtd
* Troubleshooting Projects::     How to fix project dependency problems
* View DSL Filter Reference::    Complete reference for the View DSL
* Hooks Framework Reference::    Complete guide to customization hooks


Extending org-gtd

* Project Traversal Functions::


Troubleshooting

* Finding lost tasks::
* Projects without a NEXT item::
* I can't create a project when clarifying an inbox item!::
* Configuration problems::
* Tasks still showing after tickler'ing or someday'ing project::
* Still stuck?::



File: org-gtd.info,  Node: Summary,  Prev: Top,  Up: Top

1 Summary
*********

This package tries to replicate as closely as possible the GTD workflow
(see diagram below).

   This package, and this documentation, assume familiarity with the
flow of GTD as described in the book.

   This package provides a system that allows you to capture incoming
things into an inbox, then process the inbox and categorize each item
based on the GTD categories.  It leverages org-agenda to show today's
items as well as the NEXT items.  It provides a flexible project
management system with support for both sequential and parallel task
execution.

   *New to org-gtd?*  Start with *note Getting Started with Org GTD::
for a hands-on tutorial.

   *Upgrading from 3.x?*  See *note Upgrading:: for required
configuration changes and migration steps.
                                         +-------+
                                         |"STUFF"|
                                         +---+---+
                                             |
                                         +---v---+
                                         | INBOX |
                                         +---+---+
                                             |              Eliminate  +-----------+
                                             |            +----------->|  Trash    |
                                      +------v------+     |            +-----------+
                                      | What is it? |     |
                                      +------+------+     |            +-----------+
                                             |            | Incubate   |  Someday/ |
                                             |            +----------->|   Maybe   |
     +----------+  YES (multi-step)   +------v------+  NO |            +-----------+
     | Projects |<--------------------|    Is it    |-----+
     +-+----^---+                     | Actionable? |     | File       +-----------+
       |    |   +----------------+    +------+------+     +----------->| Reference |
       |    |        Review for  |           |                         +-----------+
     +-v----+---+     Actions    |           |
     | Planning |                +---------->| YES
     +----------+                            |
                                      +------v------+     Less than
                            Delegate  | What's the  |     2 minutes    +-----------+
                          +-----------+    NEXT     +----------------->|   DO IT   |
                          |           |   Action?   |                  +-----------+
                          |           +------+------+
                          |                  |
                          |                  | FOR ME:
                          |                  |         Specific Date or Time
                          |                  +-------------------------------+
                          |              ASAP|                               |
                    +-----v-----+      +-----v-----+                   +-----v-----+
                    |           |      |           |                   |           |
                    |           |      |           |                   |           |
                    |           |      |           |                   |           |
                    |           |      |           |                   |           |
                    |           |      |           |                   |           |
                    +-----------+      +-----------+                   +-----------+
                     Waiting For        Next Actions                      Calendar

* Menu:

* What's new in 4.0: What's new in 40.
* Setting up Org GTD::
* Getting Started with Org GTD:: Tutorials to get you productive quickly
* Using Org GTD::                How Org GTD maps to the GTD flow
* Reference::                    Complete reference for all org-gtd features
* Extending org-gtd::
* Troubleshooting::


File: org-gtd.info,  Node: What's new in 40,  Next: Setting up Org GTD,  Up: Summary

1.1 What's new in 4.0
=====================

Version 4.0 is a major release that transforms how Org GTD handles
projects and configuration, while maintaining compatibility with your
existing GTD data.

* Menu:

* Flexible project dependencies (the big one!)::
* Simplified keyword configuration::
* Data-driven configuration::
* Declarative view language::
* Better project modification::
* Updated terminology Review → Reflect::
* Updated terminology Incubate → Tickler + Someday/Maybe::
* Enhanced reflect capabilities::
* Simplified configuration::
* Per-type refile prompting::
* Capture timestamps::
* What you need to do::
* Previous versions::


File: org-gtd.info,  Node: Flexible project dependencies (the big one!),  Next: Simplified keyword configuration,  Up: What's new in 40

1.1.1 Flexible project dependencies (the big one!)
--------------------------------------------------

Projects are no longer limited to sequential tasks!  You can now create
complex project structures with parallel tasks and custom dependencies.

   • *Define any dependency relationship* - Tasks can block other tasks,
     creating a directed acyclic graph (DAG) of dependencies
   • *Parallel work streams* - Multiple tasks can be NEXT at the same
     time if they don't depend on each other
   • *Automatic dependency detection* - Org GTD finds all tasks that are
     ready to work on based on the dependency graph
   • *Cycle prevention* - The system prevents circular dependencies that
     would create deadlocks
   • *Visual dependency helper* (optional) - See task relationships in a
     side window while clarifying projects

   Tasks without explicit dependencies still work sequentially (as
before), so your existing projects continue to work unchanged.


File: org-gtd.info,  Node: Simplified keyword configuration,  Next: Data-driven configuration,  Prev: Flexible project dependencies (the big one!),  Up: What's new in 40

1.1.2 Simplified keyword configuration
--------------------------------------

The new keyword configuration system is clearer and more maintainable:

   • *One mapping instead of many variables* - Replace individual
     keyword variables (‘org-gtd-next’, ‘org-gtd-todo’, etc.)  with a
     single ‘org-gtd-keyword-mapping’ structure
   • *Global TODO keywords* - No more file-level ‘#+TODO:’ lines that
     can conflict.  Use Emacs' global ‘org-todo-keywords’ configuration
     instead
   • *Automatic validation* - Org GTD validates your keyword
     configuration and provides helpful error messages if something is
     wrong
   • *Better Emacs 29+ support* - Use ‘setopt’ for automatic validation
     when setting variables

   See *note Configuration options: Tell me all the levers I can pull.
for details.


File: org-gtd.info,  Node: Data-driven configuration,  Next: Declarative view language,  Prev: Simplified keyword configuration,  Up: What's new in 40

1.1.3 Data-driven configuration
-------------------------------

New configuration system allows you to customize item properties
declaratively:

   • *Configure by item type* - Define what properties each GTD item
     type should have
   • *Prompt for user input* - Automatically prompt for dates, text, or
     custom data when organizing
   • *Extensible* - Easy to add your own custom configuration for new
     item types


File: org-gtd.info,  Node: Declarative view language,  Next: Better project modification,  Prev: Data-driven configuration,  Up: What's new in 40

1.1.4 Declarative view language
-------------------------------

Creating custom agenda views is now much easier with a declarative
syntax:

   • *Specify what you want, not how to get it* - Define views using
     simple filters instead of complex skip functions
   • *Native org-agenda integration* - Uses org-agenda's built-in skip
     functions for performance
   • *More maintainable* - View definitions are data structures, not
     code


File: org-gtd.info,  Node: Better project modification,  Next: Updated terminology Review → Reflect,  Prev: Declarative view language,  Up: What's new in 40

1.1.5 Better project modification
---------------------------------

   • *Add tasks to projects anywhere* - You can now add tasks to
     projects even if the project file is outside ‘org-gtd-directory’
   • *Modify project structure* - Commands to create task dependencies
     and manage complex projects


File: org-gtd.info,  Node: Updated terminology Review → Reflect,  Next: Updated terminology Incubate → Tickler + Someday/Maybe,  Prev: Better project modification,  Up: What's new in 40

1.1.6 Updated terminology: Review → Reflect
-------------------------------------------

Following David Allen's updated terminology from his more recent books,
all "review" and "oops" commands are now named "reflect":

   • ‘org-gtd-review-*’ → ‘org-gtd-reflect-*’
   • ‘org-gtd-oops-*’ → ‘org-gtd-reflect-*’

   The old names still work as aliases but are marked obsolete.


File: org-gtd.info,  Node: Updated terminology Incubate → Tickler + Someday/Maybe,  Next: Enhanced reflect capabilities,  Prev: Updated terminology Review → Reflect,  Up: What's new in 40

1.1.7 Updated terminology: Incubate → Tickler + Someday/Maybe
-------------------------------------------------------------

The "Incubate" category has been split into two distinct types to better
align with GTD concepts:

   • *Tickler* - Items with a specific review date (formerly
     "Incubated").  Use this for time-based reminders and paused
     projects with a date to revisit.
   • *Someday/Maybe* - Items with no specific timeframe.  Use this for
     ideas and possibilities you might pursue eventually.

   This clarifies the distinction between "remind me on a specific date"
(Tickler) and "maybe someday with no commitment" (Someday/Maybe).

   Changes:
   • ‘org-gtd-incubate’ → ‘org-gtd-tickler’ (creates tickler items with
     timestamps)
   • New ‘org-gtd-someday’ command (creates someday items without
     timestamps)
   • New ‘org-gtd-reflect-someday-review’ command - Walk through someday
     items one-by-one with single-keystroke defer/clarify/quit actions.
     Optionally group items into named lists for focused reviews.  See
     *note Reviewing Someday/Maybe Items::.
   • Property value: ‘ORG_GTD: Incubated’ → ‘ORG_GTD: Tickler’ or
     ‘ORG_GTD: Someday’

   The old ‘org-gtd-incubate’ command still works as an alias to
‘org-gtd-tickler’ but is marked obsolete.


File: org-gtd.info,  Node: Enhanced reflect capabilities,  Next: Simplified configuration,  Prev: Updated terminology Incubate → Tickler + Someday/Maybe,  Up: What's new in 40

1.1.8 Enhanced reflect capabilities
-----------------------------------

   • *Find missed items* - New ‘org-gtd-reflect-missed-items’ command to
     catch things that slipped through
   • *Better stuck project detection* - Improved identification of
     projects that need attention


File: org-gtd.info,  Node: Simplified configuration,  Next: Per-type refile prompting,  Prev: Enhanced reflect capabilities,  Up: What's new in 40

1.1.9 Simplified configuration
------------------------------

   • *org-gtd-mode has a new purpose* - The mode is no longer about
     wrapping agenda commands.  It now provides a mode-line indicator
     showing your inbox count (e.g., ‘GTD[5]’), giving you at-a-glance
     visibility into how many items need processing.


File: org-gtd.info,  Node: Per-type refile prompting,  Next: Capture timestamps,  Prev: Simplified configuration,  Up: What's new in 40

1.1.10 Per-type refile prompting
--------------------------------

You can now control refile prompting behavior for each GTD item type
independently:

   • *Fine-grained control* - Configure which item types prompt for
     refile target selection vs.  auto-refile to first target
   • *Sensible defaults* - Most item types prompt by default; quick
     actions, knowledge, and trash auto-refile
   • *Deprecates ‘org-gtd-refile-to-any-target’* - The old boolean is
     replaced by ‘org-gtd-refile-prompt-for-types’, a list of types that
     should prompt

   See *note Refiling to the appropriate area:: for configuration
details.


File: org-gtd.info,  Node: Capture timestamps,  Next: What you need to do,  Prev: Per-type refile prompting,  Up: What's new in 40

1.1.11 Capture timestamps
-------------------------

Captured items now automatically receive an ‘ORG_GTD_CAPTURED_AT’
property with an inactive timestamp recording when the item was
captured.  This is useful for:

   • *Inbox reviews* - See how long items have been sitting in your
     inbox
   • *Weekly reviews* - Identify items that have been captured but not
     processed
   • *Auditing* - Track when ideas and tasks entered your system

   This happens automatically for all captures using the default
templates.  No configuration needed.


File: org-gtd.info,  Node: What you need to do,  Next: Previous versions,  Prev: Capture timestamps,  Up: What's new in 40

1.1.12 What you need to do
--------------------------

If you're upgrading from 3.x, see the *note Upgrading section:
Upgrading. for complete step-by-step instructions.  The required changes
are:

  1. Update your keyword configuration to use ‘org-gtd-keyword-mapping’
  2. Remove any ‘#+TODO:’ lines from your GTD files
  3. *Run the migration: ‘M-x org-gtd-upgrade-v3-to-v4’* (required for
     projects to work!)

   For new installations, just configure ‘org-todo-keywords’ and
‘org-gtd-keyword-mapping’ and you're ready to go.


File: org-gtd.info,  Node: Previous versions,  Prev: What you need to do,  Up: What's new in 40

1.1.13 Previous versions
------------------------

For changes in earlier versions, see:
   • What's new in 3.0 (whats-new-3.0.org)


File: org-gtd.info,  Node: Setting up Org GTD,  Next: Getting Started with Org GTD,  Prev: What's new in 40,  Up: Summary

1.2 Setting up Org GTD
======================

* Menu:

* Upgrading::                    How to upgrade your local setup across major versions
* Installing::                   Get Org GTD in your emacs
* Configuring::                  Required and optional system configuration


File: org-gtd.info,  Node: Upgrading,  Next: Installing,  Up: Setting up Org GTD

1.2.1 Upgrading
---------------

If you are installing and not upgrading, you can skip this section
entirely and just go to the next section, *note Installing::.

   • 4.0.0 <- 3.x.x

     Version 4.0 introduces major improvements to keyword configuration
     and project management.  Your existing GTD data will continue to
     work, but you'll need to update your configuration and optionally
     migrate to take full advantage of new features.

        • Required: Configuration changes

          *1.  Update keyword configuration*

          *OLD way (version 3.x):*
               ;; Individual keyword variables (no longer used)
               (setq org-gtd-next "NEXT")
               (setq org-gtd-todo "TODO")
               (setq org-gtd-wait "WAIT")
               (setq org-gtd-canceled "CNCL")

          *NEW way (version 4.0):*
               ;; First, configure org-mode's global TODO keywords
               ;; All your GTD keywords must be in the same sequence
               (setq org-todo-keywords
                     '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

               ;; Then map GTD semantic states to your keywords
               ;; Use setopt (Emacs 29+) for automatic validation, or setq for older versions
               (setopt org-gtd-keyword-mapping
                       '((todo . "TODO")      ;; tasks not ready to be acted upon
                         (next . "NEXT")      ;; tasks ready to act on immediately
                         (wait . "WAIT")      ;; tasks blocked or delegated
                         (done . "DONE")      ;; tasks successfully completed
                         (canceled . "CNCL"))) ;; tasks that won't be completed

          Steps:
            1. Remove old keyword variables (‘org-gtd-next’,
               ‘org-gtd-todo’, ‘org-gtd-wait’, ‘org-gtd-canceled’ and
               their ‘-suffix’ variants) from your configuration
            2. Remove any ‘#+TODO:’ lines from your GTD org files
               (inbox.org, org-gtd-tasks.org, etc.)
            3. Add the global keyword configuration to your Emacs init
               file
            4. Ensure all GTD keywords appear in the *same sequence* in
               ‘org-todo-keywords’

        • Required: Configure org-agenda-files

          Before running the migration, ensure your GTD files are in
          ‘org-agenda-files’.  The migration command scans these files
          to find items to upgrade.

          For the migration to work, first load org-gtd, then set
          ‘org-agenda-files’:

               (require 'org-gtd)
               (setq org-agenda-files (list org-gtd-directory))

          Or if using ‘use-package’, put the ‘org-agenda-files’ setting
          in your ‘:config’ section.  It's important to put the
          ‘org-gtd-directory’ definition in the ‘:init’ section.

          If ‘org-agenda-files’ is not configured, the migration won't
          find anything to migrate.

        • Required: Data migration

          Version 4.0 changes how projects work internally.  *The old
          TRIGGER-based system no longer functions* - v4 uses dependency
          properties instead.  You MUST run the migration for your
          existing projects to continue working.

          *Make a backup first!*  The migration modifies your GTD files.

          *Run the migration command:*

               M-x org-gtd-upgrade-v3-to-v4

          *What the migration does:*

          The migration performs five steps automatically:

            1. *Migrates Incubated items* to Tickler or Someday:
                  • Items with ‘ORG_GTD_TIMESTAMP’: Sets
                    ‘ORG_GTD="Tickler"’
                  • Items without timestamp: Sets ‘ORG_GTD="Someday"’
                  • Level 1 heading gets ‘ORG_GTD_REFILE’ based on first
                    child's type

            2. *Adds ORG_GTD properties* to identify items:
                  • Adds ‘ORG_GTD="Projects"’ to project headings
                  • Adds ‘ORG_GTD="Actions"’ to project tasks

            3. *Migrates delegated items* to use their own type:
                  • Changes ‘ORG_GTD’ from "Actions" to "Delegated" for
                    items with ‘DELEGATED_TO’ property
                  • This separates delegated items from regular single
                    actions

            4. *Migrates habits* to use consistent property value:
                  • Sets ‘ORG_GTD="Habit"’ on all items with
                    ‘STYLE="habit"’

            5. *Converts projects to dependency-based system*:
                  • Adds ‘ORG_GTD_DEPENDS_ON’ and ‘ORG_GTD_BLOCKS’
                    properties to create sequential task chains
                  • Adds ‘ORG_GTD_FIRST_TASKS’ property to project
                    headings
                  • Updates task states (NEXT/TODO) based on the new
                    dependency graph

          *After migration:*

             • Your projects continue to work sequentially (task 1 →
               task 2 → task 3)
             • The sequential behavior is now implemented via dependency
               properties instead of TRIGGER
             • You can now customize dependencies for individual
               projects if you want parallel tasks
             • Safe to run multiple times if needed

        • Required: Acknowledge the upgrade

          After completing the upgrade, you must set
          ‘org-gtd-update-ack’ to suppress the upgrade warning.  *This
          setting must be evaluated before org-gtd loads*—otherwise the
          warning appears during package loading, before your config
          runs.

          *Why before loading?*  The warning is intentionally triggered
          at load time so you can't miss it.  Once you've completed the
          upgrade steps, you acknowledge by setting this variable in the
          ':init' section (for use-package) or before the ‘require’
          statement.

          *use-package:*
               (use-package org-gtd
                 :after org
                 :init
                 ;; Acknowledge upgrade BEFORE package loads
                 (setq org-gtd-update-ack "4.0.0")
                 :config
                 ;; Rest of your configuration...
                 (org-edna-mode 1))

          *Without use-package:*
               ;; Set BEFORE requiring org-gtd
               (setq org-gtd-update-ack "4.0.0")
               (require 'org-gtd)

          *What version to use:* Always set it to the major version
          you've upgraded to (e.g., "4.0.0").  Minor version updates
          (4.0.1, 4.1.0) generally don't require acknowledgment—only
          major upgrades with breaking changes do.

        • Why these changes?

          *Keyword configuration:*
             • Simpler: One mapping structure instead of multiple
               variables
             • More reliable: Global configuration avoids file-level
               conflicts
             • Better validation: Org GTD checks your configuration and
               provides helpful errors
             • Future-proof: Easier to extend with new keyword types

          *Property-based system:*
             • More robust: Properties work reliably across different
               org-mode features
             • More flexible: Enables features like multi-project tasks
             • Better performance: Efficient skip functions for native
               org-agenda

        • org-gtd-mode has a new purpose

          The ‘org-gtd-mode’ minor mode has been redesigned in version
          4.0.  It no longer wraps org-agenda commands—instead, it
          provides useful mode-line feedback.

          *What it does now:*
             • Displays inbox count in your mode-line (e.g., ‘GTD[5]’)
             • Includes items from both main inbox and additional inbox
               files
             • Refreshes periodically to catch external file changes

          *To enable:*
               (org-gtd-mode 1)

        • org-agenda-property has been vendored

          If you were using ‘org-agenda-property’ configuration
          variables to show properties in the agenda, you need to update
          them.  The package has been vendored into org-gtd with a new
          prefix.

          *OLD (org-agenda-property package):*
               (setq org-agenda-property-list '("LOCATION" "DELEGATED_TO"))
               (setq org-agenda-property-position 'where-it-fits)
               (setq org-agenda-property-column 60)
               (setq org-agenda-property-separator "|")

          *NEW (org-gtd-agenda-property):*
               (setq org-gtd-agenda-property-list '("LOCATION" "DELEGATED_TO"))
               (setq org-gtd-agenda-property-position 'where-it-fits)
               (setq org-gtd-agenda-property-column 60)
               (setq org-gtd-agenda-property-separator "|")

          Steps:
            1. Remove ‘org-agenda-property’ from your package
               dependencies (no longer needed)
            2. Rename any ‘org-agenda-property-*’ variables to
               ‘org-gtd-agenda-property-*’

          The functionality is identical—only the naming has changed.


File: org-gtd.info,  Node: Installing,  Next: Configuring,  Prev: Upgrading,  Up: Setting up Org GTD

1.2.2 Installing
----------------

This package requires Emacs 28.1 or higher.

   This package is on MELPA and MELPA stable under the name ‘org-gtd’.

   • use-package

     Just make sure this is loaded after ‘org-mode’ like so.
          (use-package org-gtd :after org)

   • Manually

     Check out the source code for dependencies and install them.  Then,
     clone this repo to a directory of your choice, e.g.
     ‘~/.emacs.d/packages’.  Finally, add this to your config:
          (add-to-list 'load-path "~/.emacs.d/packages")
          (require 'org-gtd)


File: org-gtd.info,  Node: Configuring,  Prev: Installing,  Up: Setting up Org GTD

1.2.3 Configuring
-----------------

   • Basic setup

     You need to configure three things for org-gtd to work:

       1. *TODO keywords*: Configure ‘org-todo-keywords’ with your GTD
          workflow states
       2. *Keyword mapping*: Map GTD semantic states to your keywords
          with ‘org-gtd-keyword-mapping’
       3. *org-edna*: Enable org-edna with inheritance for project
          dependencies to work

     *Important for existing org-mode users*: If you already have custom
     ‘org-todo-keywords’, add a separate sequence for GTD keywords
     rather than mixing them into your existing sequences.  See *note
     Required keyword configuration:: for details.

     See the configuration sections below for details.

     *Optional*: Enable ‘org-gtd-mode’ if you want to see your inbox
     count in the mode-line (e.g., ‘GTD[5]’).

   • Complete Configuration Examples

     *Configuration is the most critical part of setup.*  The examples
     below are complete, working configurations you can copy-paste into
     your init file.

        • Example 1: Vanilla Emacs (Minimal Configuration)

          This is the simplest possible configuration for org-gtd.  Copy
          this entire block into your init file:

               ;; Suppress upgrade warnings (set BEFORE org-gtd loads)
               ;; After upgrading, set to the version you upgraded to
               (setq org-gtd-update-ack "4.0.0")

               ;; Configure org-mode TODO keywords
               ;; All GTD keywords MUST be in the same sequence
               ;; Standard options like "TODO(t)" or "DONE(d!)" are fine - org-gtd ignores them
               (setq org-todo-keywords
                     '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

               ;; Map GTD semantic states to your keywords
               (setq org-gtd-keyword-mapping
                     '((todo . "TODO")      ; tasks not ready to act on
                       (next . "NEXT")      ; tasks ready to act on immediately
                       (wait . "WAIT")      ; tasks blocked or delegated
                       (done . "DONE")      ; tasks successfully completed
                       (canceled . "CNCL"))) ; tasks that won't be completed

               ;; Optional: Set GTD directory (defaults to ~/gtd/)
               ;; Must be set BEFORE org-gtd loads if you want to customize it
               ;; (setq org-gtd-directory "~/my-gtd/")

               ;; Enable per-type refile prompting (recommended)
               ;; Without this, all items auto-refile to first target without prompting
               (setq org-gtd-refile-to-any-target nil)
               ;; Customize which types prompt vs auto-refile:
               ;; (setq org-gtd-refile-prompt-for-types '(project-heading project-task ...))

               ;; REQUIRED: Enable org-edna for project dependencies
               (org-edna-mode 1)

               ;; Global keybindings for GTD commands
               ;; These work anywhere in Emacs
               (global-set-key (kbd "C-c d c") 'org-gtd-capture)
               (global-set-key (kbd "C-c d e") 'org-gtd-engage)
               (global-set-key (kbd "C-c d p") 'org-gtd-process-inbox)
               (global-set-key (kbd "C-c d n") 'org-gtd-show-all-next)
               (global-set-key (kbd "C-c d s") 'org-gtd-reflect-stuck-projects)



               ;; Keybinding for clarify map and agenda files
               ;; These only work after org-gtd loads (e.g. so org-gtd-directory is defined)
               (with-eval-after-load 'org-gtd
                 (setq org-agenda-files (list org-gtd-directory))
                 (define-key org-gtd-clarify-mode-map (kbd "C-c c") 'org-gtd-organize))

               ;; Quick task actions in agenda view
               (with-eval-after-load 'org-agenda
                 (define-key org-agenda-mode-map (kbd "C-c .") 'org-gtd-agenda-transient))

        • Example 2: Doom Emacs Configuration

          If you use Doom Emacs, add this to your ‘packages.el’:

               (package! org-gtd)

          Then add this to your ‘config.el’:

               (use-package! org-gtd
                 :after org
                 :init
                 ;; Suppress upgrade warnings (must be set before package loads)
                 (setq org-gtd-update-ack "4.0.0")
                 ;; Set GTD directory before package loads
                 (setq org-gtd-directory "~/gtd/")

                 :custom
                 (org-todo-keywords '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))
                 (org-gtd-keyword-mapping '((todo . "TODO")
                                            (next . "NEXT")
                                            (wait . "WAIT")
                                            (done . "DONE")
                                            (canceled . "CNCL")))
                 ;; Enable per-type refile prompting (recommended)
                 ;; Without this, all items auto-refile to first target without prompting
                 (org-gtd-refile-to-any-target nil)

                 :config
                 (org-edna-mode)
                 ;; Add org-gtd files to your agenda (in :config so org-gtd-directory is defined)
                 (setq org-agenda-files (list org-gtd-directory))
                 ;; Doom-style leader key bindings
                 (map! :leader
                       (:prefix ("d" . "org-gtd")
                        :desc "Capture"        "c"  #'org-gtd-capture
                        :desc "Engage"         "e"  #'org-gtd-engage
                        :desc "Process inbox"  "p"  #'org-gtd-process-inbox
                        :desc "Show all next"  "n"  #'org-gtd-show-all-next
                        :desc "Stuck projects" "s"  #'org-gtd-reflect-stuck-projects))
                 ;; Clarify map binding
                 (map! :map org-gtd-clarify-mode-map
                       :desc "Organize this item" "C-c c" #'org-gtd-organize)
                 ;; Quick task actions in agenda view
                 (map! :map org-agenda-mode-map
                       :desc "GTD quick actions" "C-c ." #'org-gtd-agenda-transient))

        • Example 3: Spacemacs Configuration

          If you use Spacemacs, add this to your
          ‘dotspacemacs/user-config’ function:

               ;; Install org-gtd
               (use-package org-gtd
                 :ensure t
                 :after org
                 :init
                 ;; Suppress upgrade warnings (must be set before package loads)
                 (setq org-gtd-update-ack "4.0.0")
                 ;; Configure org-mode TODO keywords
                 (setq org-todo-keywords
                       '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))
                 ;; Map GTD semantic states
                 (setq org-gtd-keyword-mapping
                       '((todo . "TODO")
                         (next . "NEXT")
                         (wait . "WAIT")
                         (done . "DONE")
                         (canceled . "CNCL")))
                 ;; Set GTD directory before package loads
                 (setq org-gtd-directory "~/gtd/")
                 ;; Enable per-type refile prompting (recommended)
                 ;; Without this, all items auto-refile to first target without prompting
                 (setq org-gtd-refile-to-any-target nil)

                 :config
                 ;; REQUIRED: Enable org-edna for project dependencies
                 (org-edna-mode 1)
                 ;; Add org-gtd files to your agenda (in :config so org-gtd-directory is defined)
                 (setq org-agenda-files (list org-gtd-directory))
                 ;; Spacemacs leader key bindings
                 (spacemacs/set-leader-keys
                   "od c" 'org-gtd-capture
                   "od e" 'org-gtd-engage
                   "od p" 'org-gtd-process-inbox
                   "od n" 'org-gtd-show-all-next
                   "od s" 'org-gtd-reflect-stuck-projects)
                 ;; Clarify map binding
                 (with-eval-after-load 'org-gtd
                   (define-key org-gtd-clarify-mode-map (kbd "C-c c") 'org-gtd-organize))
                 ;; Quick task actions in agenda view
                 (with-eval-after-load 'org-agenda
                   (define-key org-agenda-mode-map (kbd "C-c .") 'org-gtd-agenda-transient)))

        • What These Configurations Do

          All three examples configure the same essential pieces:

            1. *‘org-todo-keywords’* - Defines the workflow states (TODO
               → NEXT → WAIT → DONE/CNCL)
                  • The ‘|’ separator marks done states (right side) vs
                    active states (left side)
                  • All GTD keywords must be in a single sequence

            2. *‘org-gtd-keyword-mapping’* - Maps GTD concepts to your
               keyword choices
                  • ‘todo’ - Tasks not yet actionable
                  • ‘next’ - Tasks ready to work on right now
                  • ‘wait’ - Tasks blocked or delegated
                  • ‘done’ - Tasks successfully completed
                  • ‘canceled’ - Tasks that won't be done

            3. *‘org-gtd-directory’* - Where org-gtd keeps its files
               (defaults to ‘~/gtd/’)

            4. *‘org-agenda-files’* - Makes org-gtd items appear in
               agenda views

            5. *‘org-edna-mode’* - REQUIRED for projects to work

            6. *Keybindings* - Three types:
                  • *Global bindings*: Work anywhere in Emacs (capture,
                    engage, process, etc.)
                  • *Clarify map binding*: Only works when organizing
                    items in clarify buffers
                  • *Agenda map binding*: Quick task actions in agenda
                    views (‘C-c .’ for ‘org-gtd-agenda-transient’)

        • Testing Your Configuration

          After adding one of the configurations above and restarting
          Emacs, verify everything works:

          *Test 1: Capture works*

               M-x org-gtd-capture

          Expected: Opens a capture buffer for the inbox.

          If it fails: Check that ‘org-gtd-directory’ exists and you
          have write permissions.

          *Test 2: Engage works*

               M-x org-gtd-engage

          Expected: Opens an agenda view (might be empty if you haven't
          organized anything yet).

          If it fails: Check that ‘org-agenda-files’ includes your GTD
          directory.

          *Test 3: Keywords are recognized*

            1. Open any org file: ‘M-x find-file ~/test.org’
            2. Type: ‘* Test heading’
            3. Put cursor on the heading
            4. Try cycling TODO states: ‘C-c C-t’

          Expected: Should cycle through TODO → NEXT → WAIT → DONE →
          CNCL.

          If it fails: Check that ‘org-todo-keywords’ is set correctly.

          *Test 4: org-edna is enabled*

               M-x describe-variable RET org-edna-mode

          Expected: Should show "t" (enabled).

          If it fails: Make sure ‘(org-edna-mode 1)’ is in your config
          and you've restarted Emacs.

        • Common Configuration Problems

          Before troubleshooting, identify which configuration style
          you're using:
             • *Vanilla Emacs*: See *note Example 1 Vanilla Emacs:
               Example 1 Vanilla Emacs (Minimal Configuration).
             • *Doom Emacs*: See *note Example 2 Doom Emacs: Example 2
               Doom Emacs Configuration.
             • *Spacemacs*: See *note Example 3 Spacemacs: Example 3
               Spacemacs Configuration.

          Each example shows the complete, correct configuration for
          that environment.

          *Problem: "org-gtd-capture" is undefined*

          *Cause*: org-gtd package isn't installed or loaded.

          *Solution*:
             • *Vanilla Emacs*: Install from MELPA with ‘M-x
               package-install RET org-gtd RET’
             • *Doom Emacs*: Add ‘(package! org-gtd)’ to your
               ‘packages.el’ and run ‘doom sync’
             • *Spacemacs*: The ‘use-package’ form in the *note
               Spacemacs example: Example 3 Spacemacs Configuration.
               automatically installs it with ‘:ensure t’

          *Problem: Keywords don't change when I press C-c C-t*

          *Cause*: ‘org-todo-keywords’ not configured correctly.

          *Solution*: Check your configuration has this setting:
               (setq org-todo-keywords
                     '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

          Common mistakes:
             • Keywords not in quotes: Should be ‘"TODO"’ not ‘TODO’
             • Missing sequence wrapper: Need ‘'((sequence ...))’ not
               just ‘'("TODO" ...)’
             • No done separator: Need ‘|’ before ‘"DONE"’ and ‘"CNCL"’

          See the complete configuration for your environment above.

          *Problem: Projects don't advance when I mark tasks DONE*

          *Cause*: org-edna isn't enabled.

          *Solution*: All three configuration examples include
          ‘(org-edna-mode 1)’.  Make sure you have:
             • *Vanilla/Spacemacs*: ‘(org-edna-mode 1)’ in the ‘:config’
               section
             • *Doom*: ‘(org-edna-mode)’ in the ‘:config’ section (Doom
               handles the argument)

          *Problem: Can't see GTD items in agenda*

          *Cause*: GTD directory not in ‘org-agenda-files’.

          *Solution*: All three configuration examples include this.
          Check you have:
               ;; For plain elisp - must be AFTER org-gtd loads
               (with-eval-after-load 'org-gtd
                 (setq org-agenda-files (list org-gtd-directory)))

          Or if using ‘use-package’ / ‘use-package!’, put it in
          ‘:config’ (not ‘:custom’):
               :config
               (setq org-agenda-files (list org-gtd-directory))

          *Problem: Keybindings don't work*

          *Cause*: Keybindings not defined, or defined incorrectly for
          your environment.

          *Solution*:
             • *Vanilla Emacs*: Use ‘global-set-key’ for global
               commands, ‘define-key org-gtd-clarify-mode-map’ for
               clarify buffer commands
             • *Doom Emacs*: Use ‘map!’ with ‘:leader’ prefix for
               global, ‘:map org-gtd-clarify-mode-map’ for clarify
               buffer
             • *Spacemacs*: Use ‘spacemacs/set-leader-keys’ for global,
               ‘define-key’ for clarify buffer

          The clarify binding (‘C-c c’) *only works in clarify buffers*
          - you must run ‘M-x org-gtd-process-inbox’ first.

          See the complete configuration for your environment to copy
          the correct keybinding syntax.

        • Working with Your Existing Org Setup

          Already have org-mode configured with your own refile targets
          and archive location?  Org-gtd is designed to work *alongside*
          your existing setup, not replace it.

          *Quick answers:*

             • *Will org-gtd break my ‘org-refile-targets’?*  No.
               Org-gtd merges its targets with yours.  Your targets
               appear first in completion.

             • *Will org-gtd ignore my ‘org-archive-location’?*  By
               default, yes—org-gtd uses year-based archive files.  But
               you can make it respect yours with one line:
                    (setq org-gtd-archive-location nil)  ; Use your org-archive-location

          *How the merge works:*

          When you organize an item (say, as a Project), org-gtd builds
          a combined refile target list:

            1. Your ‘org-refile-targets’ (appears first)
            2. Any heading with ‘ORG_GTD_REFILE: Projects’ property
               (org-gtd's system)

          So if you have ‘org-refile-targets’ pointing to
          ‘~/org/projects.org’, that file's headings appear first.
          Org-gtd's property-marked targets appear after.

          *When to use which:*

          Scenario                       What to do
          -----------------------------------------------------------------------------------------------------------
          New to org-mode                Use org-gtd defaults.  It creates targets automatically.
          Have existing refile setup     Keep it!  Org-gtd adds to it, doesn't replace it.
          Want single archive file       Set ‘org-gtd-archive-location’ to ‘nil’, configure ‘org-archive-location’
          Want year-based GTD archives   Use org-gtd default (nothing to configure)

          *See also:* *note Refiling to the appropriate area:: for
          details on ‘ORG_GTD_REFILE’ properties, *note Cleaning up /
          archiving: Cleaning up / archiving completed work. for archive
          details.

   • Understanding Keybindings

     org-gtd uses two types of keybindings, and understanding the
     difference is important:

        • Global Keybindings

          These work *anywhere* in Emacs and let you access the main GTD
          commands:

               ;; These commands are always available:
               (global-set-key (kbd "C-c d c") 'org-gtd-capture)       ; Capture to inbox
               (global-set-key (kbd "C-c d e") 'org-gtd-engage)        ; Daily view
               (global-set-key (kbd "C-c d p") 'org-gtd-process-inbox) ; Process inbox
               (global-set-key (kbd "C-c d n") 'org-gtd-show-all-next) ; Show NEXT actions

          You can use any key combination you prefer.  The ‘C-c d’
          prefix is just a convention.

        • Clarify Map Keybindings

          These only work when you're in a *clarify buffer* (during
          inbox processing).  The most important one is:

               ;; This only works in clarify buffers:
               (define-key org-gtd-clarify-mode-map (kbd "C-c c") 'org-gtd-organize)

          *When you're in a clarify buffer:*
            1. You've called ‘org-gtd-process-inbox’ and are looking at
               an item
            2. You've edited the item to make it clear and actionable
            3. Now you press ‘C-c c’ to organize it (choose its type:
               project, single action, etc.)

          *Why the distinction?*

          The clarify map is a separate keymap because:
             • It prevents conflicts with other org-mode bindings
             • It only activates when you need it (during processing)
             • You can bind different keys for organizing without
               affecting the rest of Emacs

          *Common patterns:*

          Most users bind:
             • ‘C-c d *’ for global commands (capture, engage, process)
             • ‘C-c c’ for organizing (only in clarify buffers)

          But you can use whatever works for your workflow!

   • Required configuration of sub-packages

        • Configuring org-edna

          package: <https://www.nongnu.org/org-edna-el/>

          This configuration is *REQUIRED* for project dependencies to
          work correctly.  It enables org-edna to automatically update
          task states when you complete tasks in a project.

               (org-edna-mode 1)

        • Adding org-gtd files to your agenda

          To see org-gtd items in your agenda views, add the org-gtd
          directory to your ‘org-agenda-files’.

          *Important*: This must happen AFTER org-gtd loads, so that
          ‘org-gtd-directory’ is defined:

               ;; For plain elisp configs:
               (with-eval-after-load 'org-gtd
                 ;; If you only want GTD files in your agenda:
                 (setq org-agenda-files (list org-gtd-directory))
                 ;; Or if you have other agenda files, add GTD to the list:
                 ;; (add-to-list 'org-agenda-files org-gtd-directory)
                 )

          For ‘use-package’ configs, put this in the ‘:config’ section
          (not ‘:custom’) so it runs after the package loads.

   • configuration options for org-gtd

        • I don't care, just let me start using it

          The most direct way to find out about the configuration
          options for org-gtd is to see the customize group: ‘M-x
          customize-group RET org-gtd’.  They are all optional because
          they all come with default values.

          The only one you may want to change before starting to use Org
          GTD is ‘org-gtd-directory’, which is the directory that Org
          GTD will look to for everything it needs to do.

          The configuration options will also be mentioned in the
          relevant subsections of *note Using Org GTD::.

        • Tell me all the levers I can pull

          Make sure you also read about sub-package configuration: *note
          Required configuration of sub-packages::.

             • Required keyword configuration

               These settings are *required* for Org GTD to work
               properly:

               ‘org-todo-keywords’
                    (‘org-mode’ variable) Define your TODO keyword
                    sequences here.  All GTD keywords (TODO, NEXT, WAIT,
                    DONE, CNCL or your custom versions) *must* be in the
                    same sequence.  Example:
                         (setq org-todo-keywords
                               '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

                    *Power users note:* If you already have
                    ‘org-todo-keywords’ configured with your own
                    workflows (e.g., BACKLOG, DOING, REVIEW), don't
                    merge GTD keywords into those sequences.  Instead,
                    add a *separate* GTD sequence.  Your org-gtd items
                    could end up in an unhandled state otherwise (always
                    fixable, but annoying).  Example with multiple
                    sequences:
                         (setq org-todo-keywords
                               '((sequence "BACKLOG(b)" "DOING(o)" "REVIEW(r)" "|" "DONE(d)" "ARCHIVED(a)")
                                 (sequence "TODO(t)" "NEXT(n)" "WAIT(w)" "|" "DONE(D)" "CNCL(c)")))  ; GTD

               ‘org-gtd-keyword-mapping’
                    Map GTD semantic states to your chosen keywords.
                    This tells Org GTD which keyword means what.  The
                    five required mappings are.
                    ‘todo’
                         Tasks not ready to be acted upon
                    ‘next’
                         Tasks ready to act on immediately
                    ‘wait’
                         Tasks blocked or delegated to someone else
                    ‘done’
                         Tasks successfully completed
                    ‘canceled’
                         Tasks that won't be completed

                    Example configuration (use ‘setopt’ for Emacs 29+ to
                    get automatic validation):
                         (setopt org-gtd-keyword-mapping
                                 '((todo . "TODO")
                                   (next . "NEXT")
                                   (wait . "WAIT")
                                   (done . "DONE")
                                   (canceled . "CNCL")))

                    Or for older Emacs versions:
                         (setq org-gtd-keyword-mapping
                               '((todo . "TODO")
                                 (next . "NEXT")
                                 (wait . "WAIT")
                                 (done . "DONE")
                                 (canceled . "CNCL")))

             • Optional configuration

               ‘org-gtd-directory’
                    set this to a directory.  ‘org-gtd’ will look for
                    all its files in this directory.
               ‘org-gtd-capture-templates’
                    (!note: take care when changing this) This defines
                    the pre-filled text that will show up when capturing
                    an item to the inbox.  The only requirements are
                    that the template string must define an org-mode
                    top-level heading, and that the entry point to the
                    inbox.  That is to say, the first two characters
                    must be a single asterisk followed by a space: ‘"*
                    "’, and the entry type must be like this: ‘entry
                    (file ,#'org-gtd-inbox-path)’.  *note Adding things
                    to the inbox::.
               ‘org-reverse-note-order’
                    (‘org-mode’ variable) set this to ‘t’ to add new
                    items to the top of project tasks and to ‘nil’ to
                    add new items to the bottom of project tasks when
                    organizing an item as such.
               ‘org-gtd-organize-hooks’
                    this is a list of functions that you can use to
                    decorate each item when you clarify it.  For
                    instance, you could add a function to set the
                    effort, or the priority, or some category, etc.  By
                    default it has only one function, which lets you add
                    tags, but of course you can change this entirely.
                    *note Organizing an item: Organizing an item into
                    the system.
               ‘org-gtd-archive-location’
                    Points to a function to generate the archive file
                    dynamically.  Default value generates a file
                    suffixed with the current year.  The function has an
                    arity of zero and generates an org-mode file+outline
                    path.  *note Cleaning up / archiving completed
                    work::.
               ‘org-gtd-refile-prompt-for-types’
                    list of GTD item types that should prompt for refile
                    target selection.  Types not in the list auto-refile
                    to first target.  Requires
                    ‘org-gtd-refile-to-any-target’ to be ‘nil’.  *note
                    Controlling Refile Prompts by Item Type::.
               ‘org-gtd-delegate-read-func’
                    function that is used to prompt for a person a task
                    is delegated to.  Must return a string.  By default
                    this is set to ‘read-string’.
               ‘org-gtd-areas-of-focus’
                    list of strings representing your areas of focus
                    (horizon 2 in GTD).
               ‘org-gtd-clarify-show-horizons’
                    When clarifying, do you want the horizons buffer to
                    be shown by default, or do you prefer it hidden?
               ‘org-gtd-clarify-show-organize-help’
                    When clarifying, show a help buffer with GTD item
                    type descriptions and keyboard shortcuts.
               ‘org-gtd-clarify-project-templates’
                    Alist of strings: ‘project template name . project
                    template’ where there template is a series of tasks
                    you may want to insert automatically, if you have a
                    generic type of project that comes up a lot.
               ‘org-gtd-clarify-display-helper-buffer’
                    When ‘t’, show a dependencies helper window when
                    clarifying projects with multiple tasks.  Useful for
                    visualizing task relationships.
               ‘org-gtd-horizons-file’
                    Name of the file, in ‘org-gtd-directory’, that will
                    be displayed when the horizons buffer is displayed
                    when clarifying.
               ‘org-gtd-prefix-width’
                    how many characters to dedicate to the prefix, on
                    the left side of the TODO items, so the project
                    name, area of focus, or other context can show
                    clearly.  See *note Prefix DSL: Prefix DSL
                    Customizing the Task Prefix Column. for controlling
                    what appears in the prefix.
               ‘org-gtd-agenda-property-list’
                    List of properties to display in agenda views
                    (default: ‘'("LOCATION")’).  See *note Configuration
                    Variables Reference:: for related positioning
                    options.
               ‘org-gtd-graph-render-mode’
                    Default rendering mode for project graphs (‘'svg’ or
                    ‘'ascii’).  Terminal users should use ‘'ascii’.
                    *note Graph Rendering Modes::.
               ‘org-gtd-graph-ui-split-ratio’
                    Width ratio for graph vs.  details panel (default:
                    ‘0.7’ = 70% graph).
               ‘org-gtd-save-after-organize’
                    When ‘t’, save all modified buffers after each
                    organize step.

   • Recommended key bindings

     There's an important keymap you'll want to make the flow of
     processing the inbox smoother.  To limit impact on your emacs
     configuration, there is a specific keymap you can use.  The
     function you'll want to bind is ‘org-gtd-organize’.  I suggest ‘C-c
     c’, as in the following example.

          (define-key org-gtd-clarify-mode-map (kbd "C-c c") #'org-gtd-organize)

     For other keybindings, do what you need.  My bindings use ‘C-c d’
     as a prefix, i.e.:

     ‘C-c d c’
          ‘org-gtd-capture’
     ‘C-c d e’
          ‘org-gtd-engage’

     etc.

        • Command Center

          Alternatively, you can bind a single key to
          ‘org-gtd-command-center’, which provides a transient menu with
          access to all major org-gtd commands:

               (global-set-key (kbd "C-c d") #'org-gtd-command-center)

          The command center is organized for both discovery and quick
          access:

          *Engage* (‘e’, ‘@’, ‘n’)
               What to work on now
          *Capture & Process* (‘c’, ‘p’, ‘k’)
               Add items and process inbox
          *Reflect* (‘a’, ‘y’, ‘d’, ‘r’, ‘R’)
               Review areas, someday items, completed work
          *Review System* (‘S’, ‘M’)
               Sub-menus for stuck and missed items
          *Archive* (‘A’)
               Archive completed items

          Try it: ‘M-x org-gtd-command-center’

   • Sample Doom Emacs Config

     If you are a Doom Emacs user, then your configuration may look
     something like this:

          (use-package! org-gtd
            :after org
            :init
            ;; Set GTD directory before package loads
            (setq org-gtd-directory "~/gtd/")
            :custom
            (org-todo-keywords '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))
            (org-gtd-keyword-mapping '((todo . "TODO")
                                       (next . "NEXT")
                                       (wait . "WAIT")
                                       (done . "DONE")
                                       (canceled . "CNCL")))
            :config
            (org-edna-mode)
            ;; Add org-gtd files to your agenda (in :config so org-gtd-directory is defined)
            (setq org-agenda-files (list org-gtd-directory))
            (map! :leader
                  (:prefix ("d" . "org-gtd")
                   :desc "Capture"        "c"  #'org-gtd-capture
                   :desc "Engage"         "e"  #'org-gtd-engage
                   :desc "Process inbox"  "p"  #'org-gtd-process-inbox
                   :desc "Show all next"  "n"  #'org-gtd-show-all-next
                   :desc "Stuck projects" "s"  #'org-gtd-reflect-stuck-projects))
            (map! :map org-gtd-clarify-mode-map
                  :desc "Organize this item" "C-c c" #'org-gtd-organize))


File: org-gtd.info,  Node: Getting Started with Org GTD,  Next: Using Org GTD,  Prev: Setting up Org GTD,  Up: Summary

1.3 Getting Started with Org GTD
================================

You've configured org-gtd.  Now let's see it in action with real
examples that demonstrate why org-gtd is powerful.

* Menu:

* Quick Start Reference::
* Tutorial Your First Project::
* Tutorial Creating Your First Custom View::
* Tutorial Quick Wins and Focus Work Views::


File: org-gtd.info,  Node: Quick Start Reference,  Next: Tutorial Your First Project,  Up: Getting Started with Org GTD

1.3.1 Quick Start Reference
---------------------------

If you haven't done the 5-minute Quick Start in the README yet, do that
first.  It walks you through:
  1. Capturing a single action
  2. Processing your inbox
  3. Organizing the item
  4. Seeing it in your engage view

   That Quick Start proves the basic cycle works.  Now let's see what
makes org-gtd special: automatic project management and custom views.


File: org-gtd.info,  Node: Tutorial Your First Project,  Next: Tutorial Creating Your First Custom View,  Prev: Quick Start Reference,  Up: Getting Started with Org GTD

1.3.2 Tutorial: Your First Project
----------------------------------

You've captured and organized a single action.  That's great for simple
tasks, but GTD's real power is managing multi-step projects.  Let's
create one and watch org-gtd handle the complexity automatically.

   • What You'll Learn

        • How to capture and structure a project
        • How org-gtd automatically manages task dependencies
        • How tasks advance from TODO → NEXT when dependencies are
          satisfied
        • How the engage view shows you what's immediately actionable

   • The Project

     We'll plan a small house renovation with three sequential steps:
       1. Review blueprints
       2. Order windows
       3. Schedule carpenter

     This demonstrates sequential project execution - the default
     behavior where each task must complete before the next begins.

   • Step 1: Capture the Project

     Press ‘C-c d c’ (or ‘M-x org-gtd-capture’).

     Type (or paste) this structure:

          * House Renovation
          ** Review blueprints
          ** Order windows of the right size
          ** Schedule carpenter

     *Important*: Projects in org-gtd have a specific structure:
        • Top-level heading (‘*’) is the project name
        • Second-level headings (‘**’) are the tasks

     Press ‘C-c C-c’ to save.

   • Step 2: Process the Inbox

     Press ‘C-c d p’ (or ‘M-x org-gtd-process-inbox’).

     You'll see your project in a clarify buffer.  This is your chance
     to refine it:
        • Add details to tasks (we already added "of the right size" to
          clarify what we need)
        • Fix typos
        • Make everything crystal clear

     When you're satisfied, press ‘C-c c’ to organize.

   • Step 3: Organize as a Project

     The transient menu appears with organization options.  Press *[p]*
     for "Project".

     Watch what org-gtd does automatically:
       1. Marks the first task ("Review blueprints") as *NEXT*
       2. Marks other tasks as *TODO*
       3. Sets up dependency relationships (task 1 blocks task 2, task 2
          blocks task 3)
       4. Refiles the entire project to your projects file

     You'll see a prompt for tags (optional).  Press ‘RET’ to skip or
     add tags if you want.

     The project is now in your GTD system!

   • Step 4: View in Engage

     Press ‘C-c d e’ (or ‘M-x org-gtd-engage’).

     You'll see an agenda view showing:
        • *NEXT: Review blueprints* - This is immediately actionable
        • The project "House Renovation" appears in the list
        • Other tasks ("Order windows", "Schedule carpenter") don't show
          as NEXT - they're waiting for the first task

     This is your daily engagement view - it shows *only* what you can
     act on right now, not everything in your system.

   • Step 5: Complete the First Task

     In the agenda view, move your cursor to "Review blueprints".

     Press *t* to cycle the TODO state.

     Select *DONE*.

     *Magic happens*: Watch "Order windows of the right size"
     automatically become NEXT!

     This is org-edna in action - the automatic dependency system
     org-gtd uses.

   • Step 6: Refresh and See the Change

     Press *g* to refresh the agenda view.

     You'll now see:
        • ✓ "Review blueprints" is DONE (depending on your agenda
          settings, it may be hidden)
        • *NEXT: Order windows of the right size* - Now actionable!
        • "Schedule carpenter" is still TODO - waiting for "Order
          windows" to complete

   • What Just Happened?

     Let's understand the automatic workflow:

       1. *When you organized as a project*, org-gtd:
             • Created a dependency chain: Task 1 → Task 2 → Task 3
             • Set properties (‘ORG_GTD_BLOCKS’, ‘ORG_GTD_DEPENDS_ON’)
               to track relationships
             • Marked only the first task as NEXT

       2. *When you marked "Review blueprints" DONE*, org-gtd:
             • Checked which tasks were blocked by this one
             • Found "Order windows" had no remaining blockers
             • Automatically changed it from TODO to NEXT

       3. *"Schedule carpenter" stays TODO* because:
             • It depends on "Order windows" completing
             • org-gtd won't mark it NEXT until its dependencies are
               satisfied

     You didn't manually manage any of this.  You just *did the work*
     and marked tasks complete.  org-gtd handled the workflow
     automatically.

   • Continue the Project

     Complete "Order windows" the same way:
       1. Go to the engage view (‘C-c d e’)
       2. Find "Order windows of the right size"
       3. When done, press *t* and select *DONE*
       4. Watch "Schedule carpenter" automatically become NEXT

     When all tasks are done, the project is complete.  You can archive
     it with ‘M-x org-gtd-archive-completed-items’ during your weekly
     review.

   • Key Takeaways

        • *Projects are multi-step actions* with automatic dependency
          management
        • *Sequential execution is the default* - tasks progress one
          after another
        • *The engage view shows only actionable items* - not everything
          in your system
        • *You focus on doing work, not managing workflows* - org-gtd
          handles task progression
        • *Completing tasks automatically advances projects* - no manual
          state management needed

   • What's Next?

     This was a sequential project (A → B → C). Later, you'll learn how
     to:
        • Create *parallel tasks* (A and B can both be NEXT
          simultaneously)
        • Set *custom dependencies* (A blocks C, B blocks C, but A and B
          are parallel)
        • Manage *complex project structures* with the dependency graph

     For now, practice with a few simple sequential projects.  The
     pattern is always:
       1. *Capture* with project structure
       2. *Clarify* to make it clear
       3. *Organize* as a project
       4. *Engage* to see what's actionable
       5. *Complete* tasks and watch progression happen automatically


File: org-gtd.info,  Node: Tutorial Creating Your First Custom View,  Next: Tutorial Quick Wins and Focus Work Views,  Prev: Tutorial Your First Project,  Up: Getting Started with Org GTD

1.3.3 Tutorial: Creating Your First Custom View
-----------------------------------------------

The built-in ‘org-gtd-engage’ view is powerful, but you'll want custom
views for different contexts.  org-gtd 4.0 has a declarative View DSL
that makes this easy.  Let's create a view that shows all your active
projects.

   • What You'll Learn

        • How the View DSL works (declarative syntax)
        • How to create a simple custom view
        • How to call your view and see results
        • How to modify views for different needs

   • Why This View?

     The engage view shows *today's actionable items* - what you should
     work on right now.

     But sometimes you want the *big picture*:
        • What projects am I working on?
        • Which ones have active tasks?
        • What's the status of each project?

     This view answers those questions by showing all active projects at
     a glance.

   • Understanding the View DSL

     Views in org-gtd are *declarative* - you describe *what* you want
     to see, not *how* to find it.

     Here's the view we'll create:

          '((name . "My Active Projects")
            (type . active-project))

     Let's break this down:

     ‘name’
          What displays in the view header
     ‘type . active-project’
          Show projects with at least one active task

     That's it!  The View DSL translates this into an org-agenda view
     and shows results.

   • Creating the View Function

     Add this to your init file (after your org-gtd configuration):

          (with-eval-after-load 'org-gtd
            (defun my-org-gtd-active-projects ()
              "Show all active projects."
              (interactive)
              (org-gtd-view-show
               '((name . "My Active Projects")
                 (type . active-project)))))

     Save your init file and reload it (‘M-x eval-buffer’ or restart
     Emacs).

   • Using Your View

     Now you can call it:

          M-x my-org-gtd-active-projects

     You'll see a list of all your active projects!

   • Binding to a Key

     For quick access, bind it to a key.  Add this to your
     configuration:

          ;; If using vanilla Emacs
          (global-set-key (kbd "C-c d P") 'my-org-gtd-active-projects)

          ;; If using Doom Emacs, add to your org-gtd config:
          (map! :leader
                (:prefix "d"
                 :desc "Active projects" "P" #'my-org-gtd-active-projects))

          ;; If using Spacemacs, add to your config:
          (spacemacs/set-leader-keys "od P" 'my-org-gtd-active-projects)

     Now press ‘C-c d P’ (or your binding) to see active projects
     instantly!

   • What You'll See

     The view shows:
        • All projects that have at least one active task
        • Each project's current state (what tasks are NEXT, TODO, etc.)
        • Project names and context

     Projects that are:
        • Completely DONE - Won't appear (no active tasks)
        • Canceled - Won't appear (no active tasks)
        • Have only TODO/NEXT/WAIT tasks - Will appear

   • Experiment: Modify the View

     Try these variations to see how the View DSL works:

     *Show ALL projects (including completed):*

          (defun my-org-gtd-all-projects ()
            "Show all projects, including completed ones."
            (interactive)
            (org-gtd-view-show
             '((name . "All Projects")
               (type . project))))

     *Show stuck projects:*

          (defun my-org-gtd-stuck-projects ()
            "Show projects that have work but no NEXT actions."
            (interactive)
            (org-gtd-view-show
             '((name . "Stuck Projects")
               (type . stuck-project))))

     *Show projects in a specific area of focus* (if you use areas):

          (defun my-org-gtd-work-projects ()
            "Show only work projects."
            (interactive)
            (org-gtd-view-show
             '((name . "Work Projects")
               (type . active-project)
               (area-of-focus . "Work"))))

   • Available Filters

     For the complete View DSL reference, see *note View DSL Filter
     Reference::.

     Here are common filters you can use in your views:

     *GTD Types:*
     ‘(type . next-action)’
          Single actions ready to do
     ‘(type . delegated)’
          Items delegated to others
     ‘(type . calendar)’
          Time-specific appointments
     ‘(type . tickler)’
          Time-based reminders
     ‘(type . someday)’
          Someday/Maybe items
     ‘(type . project)’
          Multi-step outcomes
     ‘(type . habit)’
          Recurring routines

     *Computed Types:*
     ‘(type . active-project)’
          Projects with at least one active task
     ‘(type . stuck-project)’
          Projects with no NEXT/WAIT tasks
     ‘(type . completed-project)’
          Projects with all tasks done
     ‘(type . incubated-project)’
          Projects in Tickler or Someday/Maybe

     *Time Filters:*
     ‘(when . past)’
          Type's timestamp in the past (requires type)
     ‘(when . today)’
          Type's timestamp is today
     ‘(when . future)’
          Type's timestamp in the future
     ‘(scheduled . past)’
          Scheduled in the past
     ‘(deadline . past)’
          Deadline in the past

     *Completion Filters:*
     ‘(done . t)’
          Any completed item
     ‘(done . NUMBER)’
          Completed in last NUMBER days (e.g., ‘(done . 14)’)
     ‘(done . recent)’
          Completed in last 7 days
     ‘(done . past-week)’
          Completed in last week
     ‘(not-done . t)’
          Incomplete items

     *Metadata Filters:*
     ‘(area-of-focus . "Work")’
          Filter by area of focus
     ‘(todo . ("NEXT" "TODO"))’
          Filter by TODO keywords
     ‘(level . 2)’
          Filter by heading level
     ‘(priority . A)’
          Filter by priority (also supports lists and comparisons)
     ‘(effort . (< "30min"))’
          Filter by effort estimate
     ‘(clocked . (> "1:00"))’
          Filter by time clocked

     You can combine multiple filters - they all must match (AND logic).

   • Key Takeaways

        • *Views are declarative* - you describe what you want, not how
          to get it
        • *The View DSL is readable* - it's data, not complex code
        • *Views are easy to create and modify* - just change the filter
          list
        • *You can create unlimited views* - for different contexts and
          needs
        • *Native org-agenda* - efficient skip functions without
          external dependencies

   • What's Next?

     Now that you understand views, you can create:
        • *Review views* - For your weekly/monthly reviews
        • *Context views* - Show work items, home items, errands, etc.
        • *Time-based views* - Overdue items, upcoming deadlines, this
          week's schedule
        • *Focus views* - Deep work items (‘priority’, ‘clocked’), quick
          wins (‘effort’)

     Now that you can create views, let's build some that match real
     workflows.


File: org-gtd.info,  Node: Tutorial Quick Wins and Focus Work Views,  Prev: Tutorial Creating Your First Custom View,  Up: Getting Started with Org GTD

1.3.4 Tutorial: Quick Wins and Focus Work Views
-----------------------------------------------

You've learned to create views.  Now let's create views that match *how
you actually work*--views that answer: "What can I knock out in 10
minutes?"  and "What deserves my deep focus?"

   • Why This Matters

     Think about your typical day:

        • *10 minutes before a meeting* → You want quick tasks you can
          complete
        • *2-hour focus block* → You want substantial work, not busywork
        • *Weekly review* → You want to find tasks missing estimates

     These three scenarios need different views.  The engage view shows
     *everything actionable*.  These views show *what matches your
     available time and energy*.

   • Your First Quick Wins View (30 seconds)

     Let's start with the most immediately useful view: tasks under 15
     minutes.

     Try this right now in your ‘*scratch*’ buffer:

          (org-gtd-view-show
           '((name . "Quick Wins")
             (type . next-action)
             (effort . (< "15min"))))

     Place your cursor at the end and press ‘C-x C-e’.

     *What you'll see:* Only NEXT actions that have an effort estimate
     under 15 minutes.  Perfect for those short gaps in your day.

   • The Effort Filter Explained

     The ‘effort’ filter works with your items' Effort property--the
     same one org-mode uses for time estimates.

     The pattern is simple:

          (effort . (< "TIME"))    ;; less than TIME
          (effort . (> "TIME"))    ;; more than TIME
          (effort . (between "MIN" "MAX"))  ;; within range

     Time formats work how you'd expect:
        • ‘"15min"’ or ‘"0:15"’ → 15 minutes
        • ‘"1:30"’ or ‘"1h30min"’ → 1 hour 30 minutes
        • ‘"2:00"’ or ‘"2h"’ → 2 hours

     *The mental model:* Think of effort as "how big is this bite?"
     Quick wins are small bites.  Deep work is a full meal.

   • Building a Focus Work View

     Now let's create a view for when you have real time to focus.  You
     want tasks that:
        • Are important (priority A or B)
        • Are substantial (over 30 minutes)

          (org-gtd-view-show
           '((name . "Focus Work")
             (type . next-action)
             (priority . (>= B))
             (effort . (> "30min"))))

     *What this shows:* NEXT actions that are priority B or higher AND
     estimated over 30 minutes.  These are tasks worth blocking time
     for.

   • The Priority Filter Explained

     Priority in org-mode goes A (highest) → B → C (lowest).  The
     ‘priority’ filter matches this:

          (priority . A)           ;; exactly priority A
          (priority . (A B))       ;; priority A or B
          (priority . (>= B))      ;; B or higher (A and B)
          (priority . nil)         ;; no priority set

     *Important:* A is *highest* priority.  So ‘(>= B)’ means "B or
     better"--which is A and B.

     *The mental model:* Priority answers "how important is this?"
     Effort answers "how long will it take?"  Together they help you
     match tasks to your available time and energy.

   • Finding Tasks to Triage

     One more powerful pattern: finding items missing metadata.  During
     your weekly review, you want to catch tasks that need estimates.

          (org-gtd-view-show
           '((name . "Needs Effort Estimate")
             (type . next-action)
             (effort . nil)))

     ‘(effort . nil)’ matches items with NO effort property set.  Same
     works for priority:

          (org-gtd-view-show
           '((name . "Needs Priority")
             (type . next-action)
             (priority . nil)))

     These triage views help maintain your system.

   • Bonus: The Clocked Filter

     There's one more filter: ‘clocked’.  It matches by how much time
     you've *already invested* in a task.

          ;; Tasks I've started but not finished (some time clocked)
          (org-gtd-view-show
           '((name . "In Progress")
             (type . next-action)
             (clocked . (> "0:00"))))

          ;; Tasks I haven't touched yet
          (org-gtd-view-show
           '((name . "Not Started")
             (type . next-action)
             (clocked . nil)))

     *Why this is useful:* Sometimes you want to continue work you've
     already invested in.  Sometimes you want fresh tasks.  The clocked
     filter gives you both options.

   • Putting It All Together

     Here's a complete setup with three views for different contexts:

          (with-eval-after-load 'org-gtd
            (defun my-quick-wins ()
              "Tasks under 15 minutes - perfect for short gaps."
              (interactive)
              (org-gtd-view-show
               '((name . "Quick Wins (< 15min)")
                 (type . next-action)
                 (effort . (< "15min")))))

            (defun my-focus-work ()
              "Important substantial tasks - for deep work blocks."
              (interactive)
              (org-gtd-view-show
               '((name . "Focus Work")
                 (type . next-action)
                 (priority . (>= B))
                 (effort . (> "30min")))))

            (defun my-needs-estimates ()
              "Tasks missing effort or priority - for weekly review."
              (interactive)
              (org-gtd-view-show
               '(((name . "Needs Priority")
                  (type . next-action)
                  (priority . nil))
                 ((name . "Needs Effort")
                  (type . next-action)
                  (effort . nil))))))

   • Key Takeaways

        • ‘effort’ filter matches time estimates → "How big is this
          task?"
        • ‘priority’ filter matches A/B/C → "How important is this?"
        • ‘clocked’ filter matches time invested → "How much have I
          worked on this?"
        • Use ‘nil’ to find items missing metadata
        • Combine filters to match your available time and energy

   • Where to Go From Here

     You've completed the tutorials.  You now know how to:
       1. Create and manage projects (Tutorial 1)
       2. Create custom views for any context (Tutorial 2)
       3. Build quick wins, focus work, and triage views (Tutorial 3)

     *This is enough to be productive with org-gtd!*

     Read those sections as you need them.  For now, *start using what
     you've learned*:
        • Capture items as they come up
        • Process your inbox regularly (daily if possible)
        • Use the engage view to see what's actionable
        • Create a few simple projects
        • Experiment with custom views

     The best way to learn GTD is to practice the workflow.  org-gtd
     handles the complexity--you just do the work.

     For complete filter syntax and all options, see *note View DSL
     Filter Reference::.

     *Quick reference*:
        • *note Using Org GTD:: - Deep dive into daily workflow and all
          item types
        • *note Reference:: - Complete documentation for configuration,
          commands, properties, views, and hooks
        • *note Troubleshooting:: - Solutions to common problems


File: org-gtd.info,  Node: Using Org GTD,  Next: Reference,  Prev: Getting Started with Org GTD,  Up: Summary

1.4 Using Org GTD
=================

You've completed the tutorials and understand the basics.  This section
covers everything else you'll need as you use org-gtd day-to-day and
want to explore more advanced features.

* Menu:

* Your Daily Workflow::          The GTD cycle you'll practice every day
* The GTD Flow in Depth::        Detailed explanation of each GTD step
* Understanding GTD Item Types:: When to use each type in the organize menu
* Working with Projects (Advanced)::
* Automating through emacs::


File: org-gtd.info,  Node: Your Daily Workflow,  Next: The GTD Flow in Depth,  Up: Using Org GTD

1.4.1 Your Daily Workflow
-------------------------

The GTD workflow has six steps.  You'll do the first four frequently
(even daily), and the last two periodically:

  1. *Capture* - Get things out of your head into your inbox
     (‘org-gtd-capture’)
  2. *Process* - Look at each inbox item one at a time
     (‘org-gtd-process-inbox’)
  3. *Clarify* - Edit the item to make it clear and actionable
  4. *Organize* - Categorize the item (‘org-gtd-organize’)
  5. *Engage* - Look at what you can do right now (‘org-gtd-engage’)
  6. *Review* - Periodically review your system for health

   You already practiced this in the *note Getting Started tutorials:
Getting Started with Org GTD. The sections below go deeper into each
part.

   • Quick command reference

     These are the commands you'll use most:

     Command                                    What it does                           When to use it
     --------------------------------------------------------------------------------------------------------------------------
     ‘org-gtd-capture’                          Add item to inbox                      Anytime something comes up
     ‘org-gtd-process-inbox’                    Start processing inbox                 Daily (or when inbox has items)
     ‘org-gtd-organize’                         Organize current item                  During processing (in clarify buffer)
     ‘org-gtd-engage’                           See actionable items                   Daily (your "work from" view)
     ‘org-gtd-show-all-next’                    See only NEXT actions                  When you want to focus on actions
     ‘org-gtd-reflect-stuck-projects’           Find stuck projects                    Weekly review
     ‘org-gtd-reflect-someday-review’           Review someday items one-by-one        Weekly/monthly review
     ‘org-gtd-projects-fix-all-todo-keywords’   Fix task states after external edits   After mobile/web edits
     ‘org-gtd-archive-completed-items’          Archive finished items                 Weekly/monthly cleanup

     For complete command reference with detailed explanations, see
     *note Commands Reference::.

     For details on each workflow step, see the subsections below.


File: org-gtd.info,  Node: The GTD Flow in Depth,  Next: Understanding GTD Item Types,  Prev: Your Daily Workflow,  Up: Using Org GTD

1.4.2 The GTD Flow in Depth
---------------------------

Here are the domain elements of GTD that we handle:

   • Adding things to the inbox

     The trip through GTD arguably begins by adding things to the inbox.
     The inbox is a file called ‘inbox.org’ in the directory stored in
     the variable ‘org-gtd-directory’.  By default this means the file
     will be ‘~/gtd/inbox.org’.

     Org GTD provides one function to capture items: ‘M-x
     org-gtd-capture’.  In my setup I have this bound globally as such:

          (global-set-key "C-c d c" #'org-gtd-capture)

     This function uses the variable ‘org-gtd-capture-templates’ to
     define org-gtd-specific capture templates.  By default it comes
     with two templates, one to just capture a new item, and one to
     capture an item with a link to the file where you were when you
     started the capture.

     You can customize these templates as you see fit.  In order to
     maintain proper functioning of org-gtd, however, there are two
     constraints:

       1. the first two characters of the template string must be a
          single asterisk followed by a space: ‘"* "’
       2. the entry type must be like this: ‘entry (file
          ,#'org-gtd-inbox-path)’

     *See also*: *note Configuration Variables Reference:: for complete
     documentation of ‘org-gtd-capture-templates’ and
     ‘org-gtd-directory’.

   • Processing the inbox

     Processing the inbox means taking everything in the inbox, one at a
     time, and refining/categorizing them so they are instantly useful
     when you are looking at available next / scheduled actions.

     You can start processing the inbox with ‘org-gtd-process-inbox’.
     This starts a looping behavior of clarifying each item in the
     inbox.

     If you capture items from multiple sources (mobile app, email,
     different contexts), you can configure additional inbox files.
     After the main inbox is empty, processing continues through each
     additional file in order.  See ‘org-gtd-additional-inbox-files’ in
     *note Configuration Variables Reference::.

   • Clarifying each item

     Clarifying an item means editing and adding the information that
     will be most valuable to you to the item.  Note that task-specific
     information, such as appointment date, or name of person to whom it
     is delegated, or even area of focus, will be added during the
     Organize step, so don't worry about these yet.

        • How to start clarifying

          Besides ending up in here automatically while processing the
          inbox, there's two more ways to enter the clarifying flow:

          ‘org-gtd-clarify-item’
               call this from any org-mode heading to do a one-off
               clarification.
          ‘org-gtd-clarify-agenda-item’
               call this from the agenda view, if you have anything you
               want to re-clarify, or possibly clarify for the first
               time, from somewhere outside the inbox.

        • data shape requirements

          There's two general shapes you'll be looking for.  Almost
          everything will look like a simple org-mode heading.  For
          instance, ‘* Task desc’.

          The only exception will be a project, that will look like a
          top-level heading for the project description with,
          underneath, a series of second-level headings representing
          each task to be executed sequentially before the project is
          complete.

               * Project heading
               ** First task
               ** Second task
               ** Third task

        • Options and commands related to clarification

          The clarify buffers use the major mode ‘org-gtd-clarify-mode’,
          which is derived from ‘org-mode’.  There is a keymap,
          ‘org-gtd-clarify-mode-map’, that you can use to bind useful
          keybindings.

          org-gtd provides three optional helper windows during
          clarification, each controlled by a variable:

          **Horizons window** — shows your GTD horizons file for
          context:
          ‘org-gtd-clarify-show-horizons’
               set to ‘'right’, ‘'left’, ‘'top’, or ‘'bottom’ to show by
               default; ‘nil’ to hide
          ‘org-gtd-clarify-toggle-horizons-window’
               command to toggle visibility

          See *note Working with the GTD Horizons:: for more details.

          **Organize help window** — shows all GTD item types with
          keyboard shortcuts:
          ‘org-gtd-clarify-show-organize-help’
               set to ‘'right’, ‘'left’, ‘'top’, or ‘'bottom’ to show by
               default; ‘nil’ to hide
          ‘org-gtd-clarify-toggle-organize-help’
               command to toggle visibility

          **Dependencies helper window** — shows task relationships when
          clarifying projects:
          ‘org-gtd-clarify-display-helper-buffer’
               set to ‘t’ to show when clarifying projects with multiple
               tasks; ‘nil’ to hide

          Try it now: while clarifying an item, run ‘M-x
          org-gtd-clarify-toggle-organize-help’.  You'll see each type's
          purpose and what happens when you choose it.

          If you are clarifying a project, you may be interested in
          project templates:
          ‘org-gtd-clarify-project-insert-template’
               a function that will ask you to choose a template to
               insert.
          ‘org-gtd-clarify-project-templates’
               an alist of the form ‘(name . template)’ where both name
               and template are strings.  ‘name’ will be used in the
               interactive menu, and ‘template’ will be inserted in the
               buffer.

          *See also*: *note Configuration Variables Reference:: for
          complete documentation of clarification options, and *note
          Commands Reference:: for all clarification commands.

        • Duplicating items during clarification

          Sometimes one inbox item represents multiple outcomes.
          "Prepare for Monday meeting" might actually be three things:
          book the room, prepare the slides, and email the agenda.  The
          duplicate feature lets you split these apart during
          clarification.

          **Who needs this:** Anyone who captures quick notes that later
          turn out to be multiple separate actions or projects.

             • Your first duplicate in 30 seconds

                 1. While clarifying any item, press ‘C-c d’
                 2. Edit the title in the minibuffer (or keep it the
                    same)
                 3. Press ‘RET’

               That's it.  A queue window appears showing your
               duplicate.  Continue clarifying and organizing the
               original item—the duplicate waits its turn.

             • Understanding the workflow

               Think of duplicates as a "spawn" operation.  You're
               clarifying item A, and you realize it's actually A, B,
               and C.  You spawn B and C as duplicates, then:

                 1. Organize A (the original)
                 2. Automatically, B opens for clarification
                 3. Organize B
                 4. Automatically, C opens for clarification
                 5. Organize C
                 6. Done—back to where you started

               The key insight: *duplicates form a mini-session*.  You
               must process all of them before returning to your
               previous context.  This matches the GTD principle of
               fully processing what's in front of you before moving on.

             • The queue window

               When you create your first duplicate, a side window
               appears:

                    Pending (2):
                      1. Book the room
                      2. Email the agenda

               This window:
                  • Shows all queued duplicates by title
                  • Updates as you add more or process them
                  • Closes automatically when the last duplicate is
                    organized
                  • Position is configurable (default: bottom)

             • Two ways to duplicate

               Key       Command                             Behavior
               -------------------------------------------------------------------------------------------------
               ‘C-c d’   ‘org-gtd-clarify-duplicate’         Prompts for new title (current title as default)
               ‘C-c D’   ‘org-gtd-clarify-duplicate-exact’   Copies exactly, no prompt

               Use ‘C-c d’ when the duplicates have different titles
               (most common).  Use ‘C-c D’ when you want identical
               copies to organize differently (e.g., same task delegated
               to multiple people).

             • What happens if you cancel?

               If you press ‘C-c C-k’ to stop clarifying while
               duplicates are queued, you'll see:

                    2 pending duplicates:
                      - Book the room
                      - Email the agenda
                    [d]iscard all  [s]ave to inbox  [c]ancel:

                  • *Discard*: Duplicates are lost (you decided you
                    don't need them)
                  • *Save to inbox*: Duplicates are appended to your
                    inbox for later processing
                  • *Cancel*: Return to the clarify buffer (abort the
                    abort)

             • Nested duplicates

               While clarifying a duplicate, you can create more
               duplicates.  They append to the queue.  All must be
               processed before returning to your original context.

             • Data safety

               Duplicates exist only in memory until organized.  If
               Emacs crashes, they're lost.  However:

                  • Before exiting Emacs normally, you'll be prompted if
                    any clarify buffers have pending duplicates
                  • You can save them to inbox or discard them
                  • The WIP buffer itself has auto-save enabled, so your
                    clarification work is protected

             • Configuration

                    ;; Change queue window position (default: 'bottom)
                    ;; Options: 'top, 'right, 'left, 'bottom
                    (setq org-gtd-clarify-duplicate-queue-position 'right)

               *See also*: *note Commands Reference:: for
               ‘org-gtd-clarify-duplicate’ and
               ‘org-gtd-clarify-duplicate-exact’.

   • Organizing an item into the system

     When you are done clarifying, call ‘M-x org-gtd-organize’ (or hit
     your keybinding for it, see *note Recommended key bindings::).
     This will open a transient menu to let you choose how Org GTD
     should categorize this item.

     Organizing is broken up into three steps:
        • Choosing a task type (see *note Understanding GTD Item
          Types::)
        • Applying hooks to add additional relevant information (see
          *note Hooks Framework Reference::)
        • Refiling to the appropriate area (see *note Refiling: Refiling
          to the appropriate area. below)

     *See also*: *note Commands Reference:: for the ‘org-gtd-organize’
     command and all organization-related commands.

        • Refiling to the appropriate area

             • Understanding Refiling in V4

               In org-gtd v4, refiling is *optional organizational
               preference*, not a structural requirement.  Items can
               exist anywhere in your ‘org-agenda-files’.

               By default, org-gtd uses ‘ORG_GTD_REFILE’ properties to
               mark refile target headings.  These can be at *any level*
               in *any file* in ‘org-agenda-files’.

             • Refile Target System

               Org-gtd *merges* your ‘org-refile-targets’ configuration
               with its own ‘ORG_GTD_REFILE’ property-based targets:

                 1. Your configured ‘org-refile-targets’ appear first
                 2. Org-gtd's ‘ORG_GTD_REFILE’ targets appear after

               This means you can use both org-mode's standard refile
               configuration AND org-gtd's property-based system
               together.

               Org-gtd finds refile targets by searching for
               ‘ORG_GTD_REFILE’ property:

                    * Projects         <-- Can be anywhere, any level
                    :PROPERTIES:
                    :ORG_GTD_REFILE: Projects
                    :END:

                    ** Work/
                    *** Development Projects   <-- Also a valid refile target!
                    :PROPERTIES:
                    :ORG_GTD_REFILE: Projects
                    :END:

               When you organize an item as a Project, org-gtd finds
               *all* headings with ‘ORG_GTD_REFILE: Projects’ (plus any
               targets from your ‘org-refile-targets’).

                  • Controlling Refile Prompts by Item Type

                    When you have multiple refile targets, you might
                    want org-gtd to prompt for some item types but
                    auto-refile others.  For example: always prompt when
                    organizing projects (you care where they go), but
                    auto-refile quick actions (just get them out of the
                    inbox).

                    *Important:* First, you must opt into per-type
                    control by setting:

                         (setq org-gtd-refile-to-any-target nil)

                    By default ‘org-gtd-refile-to-any-target’ is ‘t’,
                    which makes org-gtd auto-refile everything without
                    prompting.

                    Once you've opted in, the
                    ‘org-gtd-refile-prompt-for-types’ variable controls
                    which types prompt.  It's a list of GTD item types
                    that should prompt for target selection:

                         ;; Default value - these types prompt for refile target:
                         (setq org-gtd-refile-prompt-for-types
                               '(single-action project-heading project-task calendar
                                 someday delegated tickler habit))

                    Item types *not* in the list auto-refile to the
                    first available target.  By default, ‘quick-action’,
                    ‘knowledge’, and ‘trash’ auto-refile.

                    *Example: Auto-refile everything except projects*

                    If you want maximum speed and only care about
                    choosing project locations:

                         (setq org-gtd-refile-prompt-for-types '(project-heading project-task))

                    *Example: Always prompt for everything*

                    If you always want to choose where items go:

                         (setq org-gtd-refile-prompt-for-types
                               '(single-action project-heading project-task calendar
                                 someday delegated tickler habit knowledge quick-action trash))

                    *Valid type symbols:* ‘single-action’,
                    ‘project-heading’, ‘project-task’, ‘calendar’,
                    ‘someday’, ‘delegated’, ‘tickler’, ‘habit’,
                    ‘knowledge’, ‘quick-action’, ‘trash’

             • Creating New Refile Targets

               To create a new refile target, add ‘ORG_GTD_REFILE’
               property to any heading:

               For Projects:
                    * My Projects
                    :PROPERTIES:
                    :ORG_GTD_REFILE: Projects
                    :END:

               For other types, use the appropriate template constant
               value:
                  • Projects: ‘ORG_GTD_REFILE: Projects’
                  • Actions: ‘ORG_GTD_REFILE: Actions’
                  • Calendar: ‘ORG_GTD_REFILE: Calendar’
                  • Tickler: ‘ORG_GTD_REFILE: Tickler’
                  • Someday: ‘ORG_GTD_REFILE: Someday’
                  • Habits: ‘ORG_GTD_REFILE: Habits’

                  • Multiple Types Per Heading

                    A single heading can accept multiple GTD types by
                    listing them space-separated:

                         * Work Tasks
                         :PROPERTIES:
                         :ORG_GTD_REFILE: Actions Projects
                         :END:

                    This heading will appear as a valid target when
                    organizing both single actions AND projects.  Useful
                    when you want to organize related items under a
                    common parent.

                    If no refile target exists when organizing, org-gtd
                    automatically creates one in your default GTD file.

             • Using Your Own Refile Targets

               If you have existing ‘org-refile-targets’ configuration,
               org-gtd automatically merges your targets with its own:

                    ;; Your refile configuration is respected and merged
                    (setq org-refile-targets '(("~/org/notes.org" :maxlevel . 2)
                                               ("~/org/work.org" :maxlevel . 3)))

               Your targets appear *first* in the refile completion
               list, followed by org-gtd's ‘ORG_GTD_REFILE’ targets.
               Files inside ‘org-gtd-directory’ are filtered by the
               ‘ORG_GTD_REFILE’ property; files outside are available
               as-is.

             • Migration from V3

               V3 required this structure:
                    * Projects      <-- MUST be level 1
                    :PROPERTIES:
                    :ORG_GTD: Projects    <-- Dual-purpose property
                    :END:

               V4 is flexible:
                    * Projects      <-- Can be anywhere, any level
                    :PROPERTIES:
                    :ORG_GTD_REFILE: Projects    <-- Marks refile target
                    :END:

               The upgrade script (‘org-gtd-upgrade-v3-to-v4’)
               automatically renames ‘ORG_GTD’ → ‘ORG_GTD_REFILE’ on
               your old category headings.

   • Engaging with your GTD items

     You can see a list of all NEXT actions, and scheduled actions, with
     ‘M-x org-gtd-engage’ .

     You can call ‘org-gtd-show-all-next’ to only see NEXT actions,
     nothing scheduled.

     You can use ‘M-x org-gtd-reflect-missed-engagements’ to find
     appointments you missed, delegated items needing check-ins, and
     late projects.  This is your safety net for catching things that
     slipped through the cracks.

     The weekly review is not yet implemented.

        • Quick Task Actions from the Agenda

             • First Contact: Why This Feature?

               When you're working from ‘org-gtd-engage’, you see your
               NEXT actions and scheduled items.  You want to mark
               things done, defer something to tomorrow, or clock in on
               a task - but you don't want to navigate away from your
               list.

               ‘org-gtd-agenda-transient’ gives you quick access to
               common task operations right from the agenda view.  One
               keypress, pick an action, and you're back to your list.

               *For GTD users* who spend time in their daily agenda and
               want to execute tasks efficiently without
               context-switching.

             • Black Triangle: Your First Quick Action

                 1. Open your engage view: ‘C-c d e’ (or ‘M-x
                    org-gtd-engage’)
                 2. Move point to any task
                 3. Press ‘C-c .’ (you'll need to set up the keybinding
                    first - see below)
                 4. Press ‘d’ to mark the task DONE

               That's it.  The task is done, and you're still in your
               agenda.

               *Setup:* Add this keybinding to your config:

                    (define-key org-agenda-mode-map (kbd "C-c .") #'org-gtd-agenda-transient)

               For ‘use-package’, add this to your ‘:bind’ section:

                    :bind
                    (:map org-agenda-mode-map
                     ("C-c ." . org-gtd-agenda-transient))

             • Understanding the Actions

               The transient menu is organized into groups based on what
               you're trying to do:

                  • State Changes

                    Change the TODO state of a task.  These are the most
                    common actions:

                       • *Mark DONE* (‘d’) - You finished it
                       • *Set WAITING* (‘w’) - You're blocked on
                         something/someone
                       • *Set NEXT* (‘n’) - It's ready to work on
                       • *Cancel* (‘x’) - It's no longer relevant
                       • *Cycle TODO* (‘t’) - Cycle through all states

                  • Time Adjustments (Conditional)

                    For Calendar, Delegated, and Tickler items only -
                    these have GTD timestamps that determine when they
                    appear.

                       • *Defer 1 day* (‘+’) - Push it to tomorrow
                         (quick snooze)
                       • *Set date* (‘s’) - Pick a new date (calls
                         ‘org-gtd-set-timestamp’)

                    Why only these types?  Calendar items have
                    appointment dates.  Delegated items have follow-up
                    dates.  Tickler items have "remind me on" dates.
                    Habits are excluded because deferring a habit has
                    different semantics (you'd break the streak).

                    *Note*: You can also call ‘org-gtd-set-timestamp’
                    directly from an org-mode heading (not just from the
                    agenda).  This is useful when editing a Calendar,
                    Delegated, or Tickler item in its source file.

                  • Clocking

                    Track time spent on tasks:

                       • *Clock in* (‘I’) - Start the clock
                       • *Clock out* (‘O’) - Stop the clock

                  • Metadata

                    Add context to tasks:

                       • *Set effort* (‘e’) - Estimate how long it'll
                         take
                       • *Set priority* (‘,’) - A/B/C priority
                       • *Set tags* (‘:’) - Add tags for filtering
                       • *Add note* (‘z’) - Append a note (logged with
                         timestamp)
                       • *Area of focus* (‘a’) - Set which life area
                         this belongs to

                  • Clarify

                    Sometimes you need to rethink a task:

                       • *Clarify (refile)* (‘c’) - Open the clarify
                         workflow, refile when done
                       • *Clarify (in place)* (‘C’) - Open the clarify
                         workflow, keep in same GTD location

             • Command Reference

               Key   Action               Description
               ----------------------------------------------------------------------
               ‘d’   Mark DONE            Complete the task
               ‘w’   Set WAITING          Mark as blocked/waiting
               ‘n’   Set NEXT             Mark as ready to work on
               ‘x’   Cancel               Cancel the task
               ‘t’   Cycle TODO           Cycle through TODO states
               ‘+’   Defer 1 day          Push to tomorrow (time-based items only)
               ‘s’   Set date             Pick new date (time-based items only)
               ‘I’   Clock in             Start time tracking
               ‘O’   Clock out            Stop time tracking
               ‘e’   Set effort           Estimate duration
               ‘,’   Set priority         Set A/B/C priority
               ‘:’   Set tags             Add/modify tags
               ‘z’   Add note             Append timestamped note
               ‘a’   Area of focus        Set life area
               ‘c’   Clarify (refile)     Re-clarify and refile
               ‘C’   Clarify (in place)   Re-clarify, keep location
               ‘q’   Quit                 Close the menu

             • Suggested Keybinding

               The command isn't bound by default because
               org-agenda-mode already has many keybindings.  The
               suggested binding is ‘C-c .’ which follows the ‘C-c’
               prefix convention for user bindings:

                    (define-key org-agenda-mode-map (kbd "C-c .") #'org-gtd-agenda-transient)


File: org-gtd.info,  Node: Understanding GTD Item Types,  Next: Working with Projects (Advanced),  Prev: The GTD Flow in Depth,  Up: Using Org GTD

1.4.3 Understanding GTD Item Types
----------------------------------

When you organize an item (‘org-gtd-organize’), a transient menu appears
with different item types.  This section explains what each type means
and when to use it.

   You already saw *Projects* and *Single actions* in the tutorials.
Here's the complete reference for all item types:

   • Single Action [S]

     *What it is*: A one-off task to do when you have time and energy.

     *When to use it*: For standalone tasks that aren't time-sensitive,
     don't depend on anyone else, and can be done whenever you're ready.

     *Examples*:
        • Buy birthday gift for Alex
        • Read article about GTD methodology
        • Update profile photo
        • Clean garage

     *What org-gtd does*:
        • Marks it as NEXT (immediately actionable)
        • Refiles to your actions file
        • Shows in ‘org-gtd-engage’ view

   • Project [P]

     *What it is*: A multi-step action requiring more than one task to
     complete.

     *When to use it*: When accomplishing your goal requires multiple
     sequential (or parallel) steps.

     *Examples*:
        • House renovation (review blueprints → order materials →
          schedule work)
        • Launch product (design → build → test → deploy → announce)
        • Plan vacation (research destinations → book flights → arrange
          accommodation)

     *What org-gtd does*:
        • Creates dependency relationships between tasks
        • Marks first task(s) as NEXT, others as TODO
        • Automatically advances tasks as you complete them
        • Refiles entire project to your projects file

     See *note Working with Projects: Working with Projects (Advanced).
     for advanced features (parallel tasks, custom dependencies).

   • Add to existing project [A]

     *What it is*: Add the current task to a project that already
     exists.

     *When to use it*: When you realize a project needs an additional
     task, or you're breaking down a project task into sub-tasks.

     *Examples*:
        • Adding "Get permits" to your house renovation project
        • Adding "Write announcement email" to your product launch
          project

     *What org-gtd does*:
        • Prompts you to choose which project
        • Inserts task into project (position depends on
          ‘org-reverse-note-order’)
        • Task keywords may need adjustment - use
          ‘org-gtd-projects-fix-todo-keywords-for-project-at-point’ on
          the project heading if needed

   • Calendar [C]

     *What it is*: An action that must be done at a specific date or
     time.

     *When to use it*: For appointments, events, or time-sensitive
     tasks.

     *Examples*:
        • Doctor appointment on Tuesday at 2pm
        • Team meeting every Monday at 9am
        • Submit report by Friday 5pm (deadline)
        • Call contractor on Thursday

     *What org-gtd does*:
        • Prompts for date/time
        • Adds timestamp to ‘ORG_GTD_TIMESTAMP’ property
        • Marks as NEXT
        • Shows in agenda views at the appropriate time

     *Note*: This is for calendar items, not scheduled work blocks.  In
     GTD, scheduling means "do this at this time," not "start working on
     this someday."

   • Delegate [D]

     *What it is*: A task someone else will do, but you need to follow
     up on.

     *When to use it*: When you're waiting for someone else to complete
     something and you need to check back.

     *Examples*:
        • Waiting for designer to finish mockups
        • Asked colleague to review document
        • IT to fix laptop issue
        • Contractor to provide estimate

     *What org-gtd does*:
        • Prompts for: person name, follow-up date
        • Sets ‘DELEGATED_TO’ property
        • Marks as WAIT
        • Shows in waiting-for views
        • Appears in agenda on follow-up date

     *Customization*: Set ‘org-gtd-delegate-read-func’ to use completion
     for names.

     *Converting actions to delegated*:

     Sometimes you start a task yourself, then realize you need to hand
     it off.  If you change any action item to WAIT (using ‘org-todo’ or
     ‘C-c C-t’), org-gtd prompts: "Convert to delegated item?"

     If you confirm, you provide who has it and when to follow up.  The
     item becomes a proper delegated item with full tracking.

     This ensures your waiting-for list always has the context GTD
     requires: who has it and when to check back.

   • Quick Action [Q]

     *What it is*: Tasks that take less than 2 minutes.

     *When to use it*: For trivial tasks you can do immediately.

     *Examples*:
        • Reply to quick email
        • File a document
        • Add item to shopping list
        • Send calendar invite

     *What org-gtd does*:
        • Marks as DONE
        • Archives immediately
        • Assumes you just did it

     *GTD principle*: If it takes less than 2 minutes, do it now.  Don't
     organize it - just do it and mark it done.

   • Tickler [I]

     *What it is*: Items with a specific review date - things you want
     to be reminded about at a future time.

     *When to use it*: For ideas, projects, or actions you're not ready
     for NOW but want to reconsider on a specific date.

     *Examples*:
        • Project paused until Q2 starts (review on April 1st)
        • Check if new API is released (review monthly)
        • Consider kitchen remodel when bonus arrives (review in June)
        • Revisit proposal after team meeting (review next week)

     *What org-gtd does*:
        • Prompts for review date
        • Sets ‘ORG_GTD_TIMESTAMP’ property with the date
        • Refiles to tickler file
        • Will remind you in agenda on that date to reconsider

     *Use case - Paused projects*: You can tickler entire projects to
     temporarily hide them from your active views while preserving all
     structure and dependencies.  See *note Tickler Projects: Tickler
     Projects Pausing Work You're Not Ready For. for details.

     *State Preservation*: Like someday items, tickler saves your item's
     current state (‘ORG_GTD’, TODO keyword, and type-specific
     properties like ‘DELEGATED_TO’).  When the review date arrives and
     you run ‘M-x org-gtd-reactivate’, you'll be prompted to confirm or
     update each property.

     *GTD principle*: The tickler file is a time-based reminder system.
     Items appear when the date arrives, prompting you to decide if
     you're ready to act.

   • Someday/Maybe [y]

     *What it is*: Ideas or possibilities with no specific timeframe -
     things you might do eventually but have no commitment to.

     *When to use it*: For ideas you want to keep but aren't ready to
     commit time or energy to, and don't need a specific review date.

     *Examples*:
        • Learn Spanish (someday)
        • Write a book (maybe)
        • Build a woodworking shop (no timeline)
        • Take photography class (when life permits)

     *What org-gtd does*:
        • Sets ‘ORG_GTD: Someday’ property (no timestamp)
        • Refiles to a someday/maybe category
        • Stays out of active views until you explicitly review it

     *Smart dispatch*: ‘org-gtd-someday’ detects what you're on:
        • Project heading → puts entire project on someday/maybe (all
          tasks)
        • Project task → puts the project it belongs to on someday/maybe
        • Single action → puts just that action on someday/maybe

     *Use case - Paused projects*: You can put entire projects on
     someday/maybe to temporarily hide them from your active views while
     preserving all structure and dependencies.  Unlike tickler, there's
     no review date—you decide when to reconsider during your reviews.

     *How to review*: Use ‘org-gtd-reflect-someday-review’ to walk
     through your someday items one by one and decide whether to keep
     deferring or reactivate them.  See *note Reviewing Someday/Maybe
     Items:: for details.

     *Key difference from Tickler*: Someday items have NO review date.
     They don't appear in your agenda automatically.  You choose when to
     review them (typically during weekly/monthly reviews).

     *GTD principle*: Someday/maybe items acknowledge possibilities
     without cluttering your active system.  They're safe to ignore
     until you're ready.

     *State Preservation*: When you move an item TO someday, org-gtd
     automatically saves its current state:
        • ‘ORG_GTD’ value → saved to ‘PREVIOUS_ORG_GTD’
        • TODO keyword → saved to ‘PREVIOUS_TODO’
        • Type-specific properties (e.g., ‘DELEGATED_TO’, ‘SCHEDULED’) →
          saved to ‘PREVIOUS_*’ versions

     This means a delegated action moved to someday will remember who it
     was delegated to, and a calendar item will remember its original
     date.

     *Reactivating Someday Items*: When you're ready to work on a
     someday item again, use ‘M-x org-gtd-reactivate’.  For non-project
     items, you'll be prompted to confirm or update each preserved
     property (e.g., "Delegated to [Jane Smith]: ").  This lets you
     adjust for the time that has passed while keeping your original
     planning work.

   • Habit [H]

     *What it is*: Recurring tasks you want to track consistently
     (org-mode habits).

     *When to use it*: For building routines and tracking streaks.

     *Examples*:
        • Exercise daily
        • Write in journal
        • Review finances weekly
        • Call parents monthly

     *What org-gtd does*:
        • Prompts for: repeat pattern (e.g., "daily", "+1w"), start date
        • Creates org-mode habit with consistency tracking
        • Shows habit graph in agenda views

     *Note*: See org-mode documentation for habit repeat patterns and
     tracking.

   • Knowledge [K]

     *What it is*: Reference information to store for later.

     *When to use it*: When the item is information to keep, not an
     action to take.

     *Examples*:
        • Recipe you want to remember
        • Quote from article
        • Meeting notes for reference
        • Product specifications

     *Important*: Choose this AFTER you've properly stored the
     information somewhere (your notes system, wiki, etc.).  This just
     marks the inbox item as "filed" and archives it.

     *GTD principle*: Separate "stuff to do" from "stuff to know."
     Knowledge goes in your reference system, not your action lists.

   • Trash [T]

     *What it is*: Not actionable, not worth keeping.

     *When to use it*: When you captured something that turns out to be
     irrelevant, already done, or not worth pursuing.

     *Examples*:
        • Event that already passed
        • Duplicate of another item
        • Idea that's no longer relevant
        • Spam/noise

     *What org-gtd does*:
        • Deletes the item
        • Doesn't archive, just removes it

     *GTD principle*: Be ruthless.  If it's not actionable and not
     valuable information, delete it.  Clutter in your system creates
     noise.

     *See also*: For technical details on how each item type is stored,
     see *note Properties Reference: Properties Reference (Internal
     Implementation).

   • Working with the GTD Horizons

     In GTD, the horizons are defined as such:

     Ground
          the day-to-day
     Horizon 1
          projects
     Horizon 2
          areas of focus
     Horizon 3
          1-2 year goals
     Horizon 4
          3-5 year vision
     Horizon 5
          purpose and principles

     Obviously, Ground and Horizons 1 are handled by the
     "capture/clarify/organize/engage" flow we've already seen.

     GTD recommends that you do not start using the horizons above
     Horizon 1 until you have both Ground and Horizon 1 under control.
     So, when you are ready...

        • Areas of focus

          Horizon 2 is now handled by a variable and a hook you can add
          to ‘org-gtd-organize-hooks’:
             • ‘org-gtd-areas-of-focus’ is a list of strings, each
               representing one of your areas of focus.
             • ‘org-gtd-set-area-of-focus’ is the hook you would add,
               e.g.  ‘(setq org-gtd-organize-hooks
               '(org-gtd-set-area-of-focus))’, it ensures each item you
               clarify will need to be part of a horizon.

          You can then use the function ‘org-gtd-reflect-area-of-focus’
          to generate an agenda view to review a specific area of focus.

          In order to add areas of focus to pre-existing items in your
          system, without going through the clarifying flow, we provide
          two functions:
             • ‘org-gtd-area-of-focus-set-on-item-at-point’, when you
               are on a org heading
             • ‘org-gtd-area-of-focus-set-on-agenda-item’, when you are
               on an agenda item

          Do note that calling the function on item at point will trust
          you blindly to do the right thing, whereas setting the area of
          focus through the agenda will attempt to recognize if you are
          on a project task and thus set the category on the project
          itself instead of the task.

        • Longer-term horizons

          The longer-term horizons can be stored in a file in the
          ‘org-gtd-directory’.  A variable governs the name of the file,
          ‘org-gtd-horizons-file’, by default ‘horizons.org’.

          At the moment it does not seem particularly useful to add any
          automation around these, since they will change so
          infrequently.

          They are, however, useful to display.

          A variable, ‘org-gtd-clarify-show-horizons’, determines
          whether/where to display the side buffer while clarifying.

          Regardless of the value of this variable, you can use the
          function ‘org-gtd-clarify-toggle-horizons-window’ to display
          or hide the side window.  If the above variable is nil, then
          the horizons window will be toggled on the right side of the
          screen.

          If your Emacs configuration or distribution doesn't enable
          ‘global-visual-line-mode’ by default, you may consider adding
          the following line at the beginning of the file containing
          your longer-term horizons:

               # -*- eval: (visual-line-mode 1); -*-

          The horizons window is narrow and enabling ‘visual-line-mode’
          locally will make sure that your horizons are easily readable
          during the clarification process.

          *See also*:
             • *note Configuration Variables Reference:: for
               ‘org-gtd-areas-of-focus’, ‘org-gtd-horizons-file’, and
               ‘org-gtd-clarify-show-horizons’
             • *note Commands Reference:: for all horizon-related
               commands
             • *note Hooks Framework Reference:: for
               ‘org-gtd-set-area-of-focus’ hook


File: org-gtd.info,  Node: Working with Projects (Advanced),  Next: Automating through emacs,  Prev: Understanding GTD Item Types,  Up: Using Org GTD

1.4.4 Working with Projects (Advanced)
--------------------------------------

You learned sequential projects in *note Tutorial Your First Project::.
This section teaches you how to handle complex projects with parallel
work streams, custom dependencies, and sophisticated project
structures—all using visual project management.

   • Quick Navigation

     This section covers:

        • *note Why Visual Project Management?: First Contact Why Visual
          Project Management?. - Understanding the motivation
        • *note Your First Project Graph View: Black Triangle Your First
          Project Graph View. - Get started in 30 seconds
        • *note Understanding Project Dependencies:: - Learn the DAG
          model
        • *note Tutorial Parallel Tasks: Tutorial Parallel Tasks with
          Graph View. - Build your first complex project
        • *note Common Dependency Patterns: Common Dependency Patterns
          (Visual Reference). - Visual reference for typical structures
        • *note Graph View Command Reference:: - Complete command
          listing
        • *note Rendering Modes: Graph Rendering Modes. - SVG vs ASCII
        • *note Complete Keyboard Reference:: - Quick reference card
        • *note Technical Details:: - Implementation and properties
        • *note Practical Tips: Practical Tips for Project Management. -
          When and how to use graph view
        • *note Troubleshooting: Troubleshooting Projects with Graph
          View. - Common problems and solutions

   • First Contact: Why Visual Project Management?

     Real projects are rarely simple sequences.  You might have:
        • Tasks that can start simultaneously (parallel research
          streams)
        • Multiple tasks that must all finish before the next step
          (convergence points)
        • Independent work paths that later merge (diamond patterns)

     Managing these mentally or through text properties is error-prone.
     You forget dependencies, create accidental bottlenecks, or miss
     opportunities for parallelization.

     *Visual project management solves this.*  You SEE your project as a
     dependency graph—boxes for tasks, arrows for dependencies, colors
     for states.  Adding tasks, creating dependencies, and understanding
     project structure becomes intuitive and immediate.

   • Black Triangle: Your First Project Graph View

     Let's see this in action right now.

        • Step 1: Find a project

          Open your engage view: ‘C-c d e’

          Find any project task in your agenda (or create a quick test
          project if you don't have one).

        • Step 2: Open the graph view

          Press ‘RET’ on the project task to jump to the project
          heading.

          Run: ‘M-x org-gtd-show-project-graph’

        • Step 3: Explore

          You're now looking at your project as a visual graph:
             • Tasks are arranged in layers from top to bottom
             • The project heading is at the bottom (it represents the
               end state after all tasks complete)
             • Arrows show which tasks block other tasks
             • Blue boxes are NEXT (ready to work on)
             • Orange boxes are TODO (waiting for dependencies)

          Press ‘?’ to see all available commands.

          *Success!*  You've visualized your first project.  Everything
          from here builds on this.

   • Understanding Project Dependencies

     Before we build complex projects, let's understand how dependencies
     work visually.

        • The Dependency Graph (DAG)

          Projects in org-gtd are *Directed Acyclic Graphs* (DAGs):

          *Directed*
               Dependencies have direction.  If Task A blocks Task B,
               the arrow points from A → B.  B can't start until A
               finishes.

          *Acyclic*
               No circular dependencies.  A → B → C → A would create a
               deadlock.  Org-gtd prevents these automatically.

          *Graph*
               Tasks can have multiple dependencies.  Task C might need
               both A AND B to finish before it can start.

        • What You See in Graph View

          The graph view arranges tasks in *layers*:

             • *Layer 0*: Root tasks (no dependencies, can start
               immediately)
             • *Layer 1*: Tasks blocked by layer 0
             • *Layer 2*: Tasks blocked by layer 1
             • And so on...

          *Blue boxes* (NEXT state) mean "ready to work on right now."
          *Orange boxes* (TODO state) mean "blocked by dependencies."

          When you complete a NEXT task, org-gtd automatically updates
          the graph:
             • Completed task disappears (or grays out if you keep DONE
               tasks visible)
             • Tasks that were waiting for it may turn blue

        • Sequential vs Parallel vs Mixed

          *Sequential* (default for new projects):
             • Tasks execute one after another: A → B → C
             • Only one task is NEXT at a time
             • Simple, linear workflow

          In graph view, sequential projects look like a vertical chain
          of boxes with arrows flowing downward.

          *Parallel*:
             • Multiple tasks can be NEXT simultaneously
             • Multiple tasks at layer 0 (all root tasks)
             • Faster project completion when tasks are independent

          In graph view, parallel projects have multiple blue boxes at
          the same layer.

          *Mixed* (most real projects):
             • Some tasks parallel, others sequential
             • Example: Research and Planning happen together, but both
               must finish before Building starts

          In graph view, mixed projects show parallel branches that
          converge at join points.

   • Tutorial: Parallel Tasks with Graph View

     Let's build a project where some tasks happen simultaneously.

        • The Scenario

          You need to "Fix Shoulder Pain":
            1. Find MRI facility (research task)
            2. Make MRI appointment (depends on finding facility)
            3. Make orthopedist appointment (independent research -
               parallel with 1 & 2)
            4. Get diagnosis (depends on both appointments completing)

          Tasks 1 and 3 can happen in parallel—they're independent
          research tasks.

        • Step 1: Capture and Organize

          Capture the project: ‘C-c d c’

               * Fix Shoulder Pain
               ** Find place to get MRI
               ** Make MRI appointment
               ** Make orthopedist appointment
               ** Get diagnosis from orthopedist

          Process the inbox: ‘C-c d p’

          Organize as a project: ‘C-c c’ → ‘[P]’

        • Step 2: Open Graph View

          From the engage view (‘C-c d e’), press ‘RET’ on any task to
          jump to the project.

          Run: ‘M-x org-gtd-show-project-graph’

          You'll see a sequential graph (the default):
               [Fix Shoulder Pain]
                       ↓
               [NEXT: Find place to get MRI]
                       ↓
               [TODO: Make MRI appointment]
                       ↓
               [TODO: Make orthopedist appointment]
                       ↓
               [TODO: Get diagnosis from orthopedist]

          We need to make tasks 1 and 3 parallel.

        • Step 3: Modify Dependencies to Create Parallel Tasks

          We need to make "Make orthopedist appointment" a root task
          (parallel to "Find place to get MRI").

          In graph view, you can modify existing dependencies:

            1. Select "Make orthopedist appointment" in the graph (use
               navigation keys)
            2. Press ‘B’ to modify blockers (remove the blocker that
               makes it sequential)
            3. Press ‘S’ to modify successors (connect it to "Get
               diagnosis")

          Alternatively, use ‘t r’ to remove a task from the project and
          re-add it where you need it.

        • What Graph View CAN Do

          From the project heading in graph view, press ‘?’ to open the
          command menu:

          ‘r’
               Add a root task (no dependencies, starts immediately)
          ‘s’
               Add a successor (a new task that depends on the selected
               task)
          ‘b’
               Add a blocker (a new task that the selected task depends
               on)

          *The key insight:* ‘s’ and ‘b’ let you connect ONE new task to
          MULTIPLE existing tasks using a checkbox menu.  This enables
          complex patterns like convergence (diamond).

        • Building Our Parallel Structure

          Let's build the correct structure from scratch:

            1. Start with project heading selected
            2. ‘r’ → "Find place to get MRI" (root task 1)
            3. ‘r’ → "Make orthopedist appointment" (root task 2 - now
               parallel!)
            4. Select "Find place to get MRI"
            5. ‘s’ → "Make MRI appointment" → check only "Find MRI" →
               RET
            6. Now select "Make MRI appointment"
            7. ‘s’ → "Get diagnosis"
            8. *Here's the key step:* The checkbox menu shows ALL
               project tasks.  Check BOTH "Make MRI appointment" AND
               "Make orthopedist appointment"
            9. Press ‘RET’ to apply

          Now "Get diagnosis" is blocked by BOTH appointments - a
          convergence point!

        • The Diamond Pattern in Action

          What we just built:

               [Find MRI - NEXT]    [Make Ortho Appt - NEXT]
                       ↓                    ↓
               [Make MRI Appt - TODO]      │
                       ↓                   │
                       └───────┬───────────┘
                               ↓
                      [Get Diagnosis - TODO]

          Two parallel paths converging at "Get diagnosis".  This is the
          diamond pattern.

        • Alternative Approach: Add Blockers

          You could also build this using ‘b’ (add blocker):

            1. Create "Get diagnosis" first as a root task (‘r’)
            2. Select "Get diagnosis"
            3. ‘b’ → "Make MRI appointment" → check "Get diagnosis" →
               RET
            4. Still on "Get diagnosis", ‘b’ → "Make orthopedist
               appointment" → check "Get diagnosis" → RET
            5. Continue building backwards...

          Both approaches work.  Use whichever feels more natural for
          your mental model.

   • Tutorial: Complex Dependencies with Graph View

        • The Scenario

          "Release Next Version of Software":

            1. List features (starting task)
            2. Implement features (depends on list)
            3. Write documentation (can start after list, parallel with
               implement)
            4. Get beta tester feedback (depends on both implement AND
               documentation)
            5. Update code based on feedback (depends on beta feedback)
            6. Update documentation based on feedback (depends on beta
               feedback, parallel with code updates)
            7. Release (depends on both updates completing)

        • The Dependency Graph

               List Features
                   ├──→ Implement Features ───┐
                   └──→ Write Documentation ───┼──→ Get Beta Feedback
                                               │         ├──→ Update Code ─────┐
                                               │         └──→ Update Docs ──────┼──→ Release
                                               └───────────────────────────────┘

        • Building with Graph View

          Starting from the project heading, open the command menu with
          ‘?’:

            1. ‘r’ → "List features" (root task)
            2. Select "List features"
            3. ‘s’ → "Implement features" → check "List features" → RET
            4. Go back to "List features"
            5. ‘s’ → "Write documentation" → check "List features" → RET

          Now you have two parallel branches from "List features".

        • Creating the Convergence Point

          For "Get Beta Feedback" that depends on BOTH implement AND
          documentation:

            1. Select "Implement features"
            2. ‘s’ → "Get Beta Feedback"
            3. In the checkbox menu, check BOTH "Implement features" AND
               "Write documentation"
            4. Press ‘RET’

          Now "Get Beta Feedback" has two blockers - it won't become
          NEXT until both are complete.

        • Building the Rest

          Continue building the parallel update paths:

            1. Select "Get Beta Feedback"
            2. ‘s’ → "Update code" → check "Get Beta Feedback" → RET
            3. Select "Get Beta Feedback" again
            4. ‘s’ → "Update docs" → check "Get Beta Feedback" → RET

          For the final convergence at "Release":

            1. Select "Update code"
            2. ‘s’ → "Release"
            3. Check BOTH "Update code" AND "Update docs"
            4. Press ‘RET’

        • The Complete Graph

                          [List Features - NEXT]
                             /              \
                            ↓                ↓
               [Implement - TODO]    [Write Docs - TODO]
                            \                /
                             ↓              ↓
                        [Get Beta Feedback - TODO]
                             /              \
                            ↓                ↓
                  [Update Code - TODO]  [Update Docs - TODO]
                             \              /
                              ↓            ↓
                           [Release - TODO]

        • Key Patterns This Example Shows

            1. *Parallel branches* from List Features (using ‘s’ twice
               from same parent)
            2. *Converging paths* at Get Beta Feedback (using
               multi-select checkbox)
            3. *Parallel updates* after feedback (using ‘s’ twice)
            4. *Final convergence* at Release (using multi-select
               checkbox)

          All four patterns are fully supported.

   • Common Dependency Patterns (Visual Reference)

     Here's what different patterns look like in graph view:

        • Sequential Chain (A → B → C)

               [A - NEXT]
                   ↓
               [B - TODO]
                   ↓
               [C - TODO]

          *When to use*: Order matters, each task depends on the
          previous.

          *How to build*: ‘r’ for A, select A, ‘s’ for B (check A),
          select B, ‘s’ for C (check B).

          *Example*: Review blueprints → Order windows → Schedule
          carpenter

        • Parallel Independent (A, B, C all start together)

               [A - NEXT]  [B - NEXT]  [C - NEXT]

          *When to use*: Tasks are completely independent, all can start
          immediately.

          *How to build*: From project heading, ‘r’ for each task.

          *Example*: Research destinations, Check budget, Ask for time
          off (vacation planning)

        • Fan-out (A → B, A → C, A → D)

                     [A - NEXT]
                    /    |    \
                   ↓     ↓     ↓
               [B-TODO][C-TODO][D-TODO]

          *When to use*: Initial work enables multiple independent
          paths.

          *How to build*: ‘r’ for A, select A, then ‘s’ three times (B,
          C, D - each checking only A).

          *Example*: Get project approval → (Design UI, Write backend
          API, Setup infrastructure)

        • Fan-in / Convergence (A → C, B → C)

               [A - NEXT]  [B - NEXT]
                     \        /
                      ↓      ↓
                     [C - TODO]

          *When to use*: Final task needs all previous work completed.

          *How to build*: ‘r’ for A and B.  Select A, ‘s’ for C, then
          check BOTH A and B in the checkbox menu.

          *Example*: (Write code, Write tests) → Merge to main

        • Diamond (A → B → D, A → C → D)

                   [A - NEXT]
                    /      \
                   ↓        ↓
               [B-TODO] [C-TODO]
                   \      /
                    ↓    ↓
                  [D-TODO]

          *When to use*: Work splits, proceeds in parallel, then
          combines.

          *How to build*:
            1. ‘r’ for A
            2. Select A, ‘s’ for B (check A)
            3. Select A again, ‘s’ for C (check A)
            4. Select B, ‘s’ for D, then check BOTH B and C

          *Example*: Research → (Write content, Design graphics) →
          Publish article

   • Graph View Command Reference

     This is the complete command reference for expert users.

     *Most operations require the transient menu:* Press ‘?’ to access
     all commands.

        • Opening Graph View

          ‘M-x org-gtd-show-project-graph’

          *Requires*: Point must be on a project heading (not a task),
          or will prompt for project selection

          *Creates*: Interactive SVG buffer named ‘*Org GTD Graph:
          <project-name>*’

        • Tier 1: Single-Key Commands (Always Available)

          These are the most frequently used commands, available without
          any prefix.

          *Navigation:*

          Key     Command            Description
          ----------------------------------------------------------------------------------
          n       Down dependency    Move to a task this one blocks
          p       Up dependency      Move to a task that blocks this one
          TAB     Next sibling       Next sibling task (see ‘org-gtd-graph-sibling-mode’)
          S-TAB   Previous sibling   Previous sibling task
          G       Goto node          Jump to task by name (with completion)

          *What counts as a "sibling"?*  By default, siblings are tasks
          that share at least one blocker (tasks blocked by the same
          thing).  You can customize this with
          ‘org-gtd-graph-sibling-mode’.  See *note Sibling Mode
          Configuration: org-gtd-graph-sibling-mode.

          *Add Tasks:*

          Key   Command         Description
          -------------------------------------------------------------------------------
          r     Add root task   Create task with no dependencies (starts immediately)
          s     Add successor   Create task that the selected task must complete first
          b     Add blocker     Create task that must complete before selected task

          *Understanding successors and blockers:*

          These two commands handle all dependency relationships:

             • *Add successor* (‘s’): "What comes after this task?"
               Creates a new task that depends on the selected task.
               The selected task blocks the new task.

             • *Add blocker* (‘b’): "What must happen first?"  Creates a
               new task that the selected task depends on.  The new task
               blocks the selected task.

          Both commands:
            1. Prompt you to select an existing task OR type a new task
               title
            2. If creating new: ask whether to clarify/organize it or
               create as simple action
            3. Let you choose multiple edges (which tasks to connect)
               via checkbox menu
            4. Automatically refresh the graph

          *After adding*: Graph automatically refreshes to show new task
          and dependencies.

          *Modify Relationships:*

          Key   Command             Description
          ------------------------------------------------------------------------
          B     Modify blockers     Toggle which tasks block the selected task
          S     Modify successors   Toggle which tasks the selected task blocks

          These commands open a checkbox menu showing all project tasks.
          Toggle checkboxes to add/remove relationships, then press
          ‘RET’ to apply.

          *View:*

          Key   Command            Description
          ----------------------------------------------------------------------
          ?     Show menu          Display transient menu with all commands
          g     Refresh            Rebuild graph (use after external changes)
          v     Toggle rendering   Switch between SVG and ASCII rendering
          q     Quit               Close graph view, keep buffer

        • Tier 2: Prefixed Commands

          These commands are used less frequently and use key prefixes
          for organization.

          *Task Operations (‘t’ prefix):*

          Key   Command               Description
          ------------------------------------------------------------------------------
          t t   Change TODO state     Cycle through TODO states
          t r   Remove from project   Remove task from this project (keeps task)
          t d   Trash task            Mark task canceled and remove from all projects
          t e   Edit in org file      Jump to task in org file for editing
          t i   Show relationships    Display all relationships for selected task

          *Project Operation:*

          Key   Command            Description
          ----------------------------------------------------------------------------------
          C     Cancel project     Cancel all incomplete tasks (prompts for confirmation)
          I     Incubate project   Move entire project to tickler (with review date)
          S     Someday project    Move entire project to someday/maybe (no review date)

          *Graph View Operations:*

          Key   Command         Description
          ----------------------------------------------------------
          Q     Quit and kill   Close graph view and kill buffer
          x s   Export SVG      Export graph as SVG file
          x d   Export DOT      Export graph as Graphviz DOT file
          x a   Export ASCII    Export graph as ASCII text file

        • Visual Indicators

             • *Blue boxes*: NEXT tasks (ready to work on)
             • *Orange boxes*: TODO tasks (blocked by dependencies)
             • *Arrows*: Dependencies (from blocker → blocked task)
             • *Layers*: Vertical positioning shows dependency depth

        • Operations Not Available in Graph View

          Some operations are standard org-mode functionality and must
          be done in the org file:

          *Changing task properties*:
             • TODO state: Use ‘t t’ in graph view, or ‘C-c C-t’ in org
               file
             • Deadlines/schedules: ‘C-c C-d’, ‘C-c C-s’ in org file
             • Task title/description: edit in org file
             • Tags/properties: edit in org file

          *Task removal*: Use ‘t r’ to remove a task from the project
          (keeps task) or ‘t d’ to trash it (marks canceled).  Completed
          tasks still show in graph view to maintain project history.

          *Access org file*: Press ‘RET’ on any task in graph view to
          jump to it in the org file.

        • Text-Based Alternatives

          Most users will find the graph view intuitive for dependency
          management.  However, DWIM (Do What I Mean) commands work from
          any context (org buffer, agenda, or graph view):

             • ‘org-gtd-project-add-successor’ - Add a task that depends
               on current task
             • ‘org-gtd-project-add-blocker’ - Add a task that blocks
               current task
             • ‘org-gtd-project-add-root-task’ - Add a task with no
               dependencies
             • ‘org-gtd-project-remove-task’ - Remove task from project
               (keeps task)
             • ‘org-gtd-project-trash-task’ - Remove and cancel task
             • ‘org-gtd-project-change-state’ - Change TODO state

          For lower-level dependency manipulation:

             • ‘org-gtd-task-add-blockers’ - Add blockers via text
               interface
             • ‘org-gtd-task-remove-blockers’ - Remove blockers via text
               interface
             • ‘org-gtd-task-show-relationships’ - Display relationships
               in minibuffer
             • ‘org-gtd-validate-project-dependencies’ - Validate
               project structure

          See *note Task Dependency Commands:: for details.

   • Graph Rendering Modes

     The graph view supports two rendering modes that you can toggle
     between at any time.  Configure the default mode with
     ‘org-gtd-graph-render-mode’.

        • SVG Mode (Default)

          High-quality graphical rendering with:
             • Smooth curves for dependency arrows
             • Anti-aliased text
             • Visual polish
             • Larger display area
             • Better for GUI Emacs

          Set as default with:
               (setq org-gtd-graph-render-mode 'svg)

        • ASCII Mode

          Text-based rendering using box-drawing characters:
             • Works in terminal Emacs
             • Accessible for screen readers
             • Compact display
             • No external dependencies
             • Uses Unicode box-drawing glyphs

          Set as default with:
               (setq org-gtd-graph-render-mode 'ascii)

        • Toggling Modes

          Press ‘v’ while in graph view to toggle between SVG and ASCII
          rendering.

        • Troubleshooting ASCII Rendering

          If ASCII rendering looks broken:
             • Ensure your terminal supports UTF-8 box-drawing
               characters
             • Try SVG mode (‘v’ to toggle)
             • Check that your font supports box-drawing glyphs
             • Verify ‘(char-displayable-p ?│)’ returns ‘t’

   • Complete Keyboard Reference

     This is a comprehensive quick reference for all graph view
     keybindings.

        • Tier 1: Single Keys

          Key           Action
          ---------------------------------------------------------
          ‘?’           Show command menu (transient)
          ‘n’           Down dependency (to task this blocks)
          ‘p’           Up dependency (to task that blocks this)
          ‘TAB’         Next sibling (same layer)
          ‘<backtab>’   Previous sibling
          ‘G’           Go to task by name
          ‘r’           Add root task (no dependencies)
          ‘s’           Add successor (task that this blocks)
          ‘b’           Add blocker (task that blocks this)
          ‘B’           Modify blockers (bulk toggle)
          ‘S’           Modify successors (bulk toggle)
          ‘g’           Refresh graph (rebuild from org file)
          ‘v’           Toggle ASCII/SVG rendering
          ‘q’           Quit graph view

        • Tier 2: Task Operations (‘t’ prefix)

          Key     Action
          ------------------------------------------
          ‘t t’   Change TODO state
          ‘t r’   Remove task from project
          ‘t d’   Trash task (cancel and remove)
          ‘t e’   Edit task in org file (jump to)
          ‘t i’   Show relationships for task

        • Tier 2: Project and View Operations

          Key     Action
          -----------------------------------------------
          ‘I’     Incubate project (tickler with date)
          ‘S’     Someday project (no review date)
          ‘C’     Cancel project (cancel all tasks)
          ‘Q’     Quit and kill buffer
          ‘x s’   Export as SVG
          ‘x d’   Export as DOT
          ‘x a’   Export as ASCII

   • Auto-Refresh on File Changes

     Graph view automatically watches the org file and refreshes when
     changes are detected (with 300ms debounce).  This means:

        • Changes in the org file appear in graph view automatically
        • No need to manually refresh after external edits
        • Multiple graph views of the same project stay in sync
        • File watching is buffer-local and cleaned up on quit

     You can still manually refresh with ‘g’ if needed.

   • Technical Details

        • Graph Data Structure

          Projects are represented as *Directed Acyclic Graphs* (DAGs):

             • *Directed*: Dependencies have direction (A blocks B, not
               vice versa)
             • *Acyclic*: No circular dependencies (org-gtd prevents
               these)
             • *Graph*: Tasks can have multiple blockers and multiple
               dependents

        • Layout Algorithm

          The Sugiyama layout algorithm:
            1. Assigns tasks to layers based on dependency depth
            2. Minimizes edge crossings between layers
            3. Centers nodes horizontally for visual balance
            4. Calculates smooth curved arrows (SVG) or line-drawing
               characters (ASCII)

        • Properties Used

          Graph view reads and writes these org properties:

             • ‘ORG_GTD_FIRST_TASKS’ (on project heading):
               Space-separated list of task IDs with no dependencies
             • ‘ORG_GTD_DEPENDS_ON’ (on tasks): Space-separated list of
               task IDs this task depends on
             • ‘ORG_GTD_BLOCKS’ (on tasks): Space-separated list of task
               IDs this task blocks
             • ‘ORG_GTD_PROJECT_IDS’ (on tasks): Space-separated list of
               project IDs this task belongs to

          These properties maintain bidirectional consistency.  When you
          add dependency A→B:
             • A's ‘ORG_GTD_BLOCKS’ includes B's ID
             • B's ‘ORG_GTD_DEPENDS_ON’ includes A's ID

          You typically don't edit these properties directly—use graph
          view commands or the text-based alternatives.

        • Undo/Redo Support

          Currently, undo/redo is not implemented in graph view.  Graph
          modifications are immediately saved to the org file.

          To undo changes:
             • Switch to the org file buffer
             • Use ‘C-x u’ (undo) as normal
             • The graph view will auto-refresh to show the reverted
               state

   • Practical Tips for Project Management

        • When to Use Graph View

             • *Planning complex projects*: Visualize before committing
               to structure
             • *Understanding stuck projects*: See why tasks are blocked
             • *Weekly review*: Quick visual health check of all
               projects
             • *Adding tasks mid-project*: Add with correct dependencies
               immediately

        • When to Use Sequential (Default)

             • Order truly matters (can't install before purchasing)
             • You're unsure what the next task will be until you
               complete current one
             • The project is simple (3-4 tasks)
             • You don't want to think about dependencies

          *Just organize as project* (‘C-c c’ → ‘[P]’) and you're done.

        • When to Create Parallel Structures

             • You have multiple people working on the project
             • Tasks are independent and could be done in any order
             • You want to optimize for speed
             • You know all tasks upfront

          *Use ‘r’ multiple times* from graph view to create parallel
          roots.

        • Managing Complexity

             • *Start sequential, add parallel only when needed*: Don't
               over-engineer.
             • *Use graph view to understand before modifying*:
               Visualize first.
             • *Keep task names clear and specific*: "Research venues"
               not "Research"
             • *Review stuck projects weekly*: ‘M-x
               org-gtd-reflect-stuck-projects’

        • Growing Projects Over Time

          As projects evolve, you need to add tasks:

             • *New independent work stream*: ‘r’ (add root task)
             • *Next step in sequence*: Select current task, ‘s’ (add
               successor)
             • *Prerequisite for existing task*: Select existing task,
               ‘b’ (add blocker)

          After adding, the graph refreshes automatically.

        • Canceling Projects

          There are three ways to cancel a project.  All of them prompt
          for confirmation and then mark all incomplete child tasks as
          CNCL, preserving any tasks already marked DONE.

             • *From graph view*: Press ‘C’ to cancel the project you're
               viewing.
             • *From the agenda*: ‘M-x
               org-gtd-project-cancel-from-agenda’ on a project task.
             • *From a project heading*: ‘M-x org-gtd-project-cancel’
               with point on the project heading.

          Additionally, when ‘org-gtd-mode’ is enabled, manually
          changing a project heading's state to CNCL (e.g., via ‘C-c
          C-t’) will trigger the same confirmation and
          child-cancellation behavior.  If you decline, the heading
          reverts to its previous state.  This means you can cancel a
          project naturally through org-mode's state cycling without
          needing a special command.

   • Exporting Project Graphs

        • First Contact: What is Graph Export?

          Graph export saves your project visualization as a file.
          Share project plans with teammates who don't use Emacs.
          Include project graphs in presentations or documentation.
          Process graphs with external tools like Graphviz.

          Three export formats:
             • *SVG*: High-quality graphics for documents and
               presentations
             • *DOT*: Graphviz source for custom styling and layouts
             • *ASCII*: Text-based diagrams for terminals and plain-text
               documentation

          Who needs this?  Anyone collaborating outside Emacs, creating
          documentation, or using graph analysis tools.

        • Tutorial: Export Your First Graph

          Let's export a project graph in under 30 seconds:

            1. Open any project in graph view: ‘M-x
               org-gtd-show-project-graph’
            2. Press ‘?’ to open the command menu
            3. Press ‘E s’ to export as SVG
            4. Choose a filename (e.g., ‘project-plan.svg’)
            5. Done!  Open the file in any image viewer or web browser

          The exported graph preserves your current view, including
          which task is selected (highlighted).

        • Progressive Learning: Choosing Export Formats

          **Start with SVG** when you first need to export.  It works
          everywhere—documents, presentations, web pages, email
          attachments.  Your colleague can open it in any browser.

          **Use DOT when you need control**.  The DOT format is
          Graphviz's source language.  Export to DOT when you want to:
             • Change colors, fonts, or layout algorithms
             • Combine multiple project graphs
             • Generate different output formats (PNG, PDF, PostScript)
             • Integrate with automated build systems

          Process a DOT file with Graphviz:
               dot -Tpng project.dot -o project.png      # Convert to PNG
               dot -Tpdf project.dot -o project.pdf      # Convert to PDF
               neato -Tsvg project.dot -o custom.svg     # Different layout algorithm

          **Use ASCII for text contexts**.  ASCII export creates
          terminal-friendly diagrams.  Use when:
             • Writing plain-text documentation (README files)
             • Sharing in chat or email where images don't work
             • Reviewing projects over SSH without graphics
             • Creating quick diagrams for code comments

          Example ASCII output:
               Conference Planning
               ├─ Research venues
               ├─ Create budget
               │  └─ Get quotes
               └─ Book venue

          **Handling large projects**: All formats work with complex
          graphs, but consider:
             • SVG scales perfectly (zoom without quality loss)
             • DOT can be processed with different layout algorithms for
               readability
             • ASCII may become unwieldy with 20+ tasks (switch to SVG)

        • When Exports Differ from Display

          The export reflects your current graph state.  If you've
          selected a task (navigated with ‘j~/~k’ or clicked), that task
          appears highlighted in the export.

          To export without highlighting:
            1. Press ‘ESC’ to deselect the current task
            2. Export with ‘E s’, ‘E d’, or ‘E a’
            3. The export shows all tasks unhighlighted

          Changes you make in graph view are immediately saved to the
          org file, so exports always reflect the actual project
          structure.

        • Reference: Export Commands

          From graph view (‘M-x org-gtd-show-project-graph’), use the
          ‘x’ prefix:

          Key     Command                        Format   Best For
          -------------------------------------------------------------------------------------
          ‘x s’   ‘org-gtd-graph-export-svg’     SVG      Documents, presentations, sharing
          ‘x d’   ‘org-gtd-graph-export-dot’     DOT      Graphviz processing, customization
          ‘x a’   ‘org-gtd-graph-export-ascii’   ASCII    Terminals, plain-text docs

          All commands prompt for a filename.  The file is created
          immediately.

        • Troubleshooting Exports

          **"No graph to export" error**: You must be in a graph view
          buffer.  Open a project graph first with ‘M-x
          org-gtd-show-project-graph’.

          **Empty or corrupted file**:
             • Verify the graph displays correctly before exporting
             • Press ‘g’ to refresh the graph view
             • Try exporting to a different location with write
               permissions

          **SVG won't open in browser**: Ensure the filename ends in
          ‘.svg’.  Most programs detect format by file extension.

          **DOT processing fails**: Install Graphviz (‘dot’ command) on
          your system.  The DOT file is plain text—open it in any editor
          to verify its contents.

   • Troubleshooting Projects with Graph View

        • Project is Stuck (has TODO tasks but no NEXT)

          Run ‘M-x org-gtd-reflect-stuck-projects’ to find stuck
          projects.

          Open the stuck project in graph view: ‘M-x
          org-gtd-show-project-graph’

          *What to look for*:
             • *No blue boxes?*  All tasks might be waiting for
               dependencies that are DONE.  Press ‘g’ to refresh.
             • *Orange boxes at layer 0?*  These should be blue (root
               tasks are never blocked).  Something's wrong with the
               dependency structure.
             • *Circular dependency?*  Org-gtd prevents these, but if
               you see arrows forming a loop, you've found a bug.

          *How to fix*:
             • Use graph view to understand the structure
             • Add a new root task (‘r’) if nothing can start
             • Refresh (‘g’) after any changes

        • Task Should Be NEXT But Shows as TODO

          In graph view, look at the task:
             • Is it orange (TODO)?
             • Trace arrows pointing TO it—these are its blockers
             • Are all those blockers blue?  Then something's wrong.
             • Are some blockers orange?  Then the task is correctly
               blocked.

          If blockers are actually DONE but still showing as blue, press
          ‘g’ to refresh.

          *How to fix*: Use ‘B’ to modify blockers (uncheck incorrect
          ones), or use text command ‘org-gtd-task-clear-relationships’
          to start fresh.

        • Too Many Tasks Are NEXT

          In graph view:
             • Count blue boxes
             • If you have 10+ blue tasks, you probably have dependency
               problems
             • Some tasks should depend on others but don't

          *How to fix*:
             • Select a task that should be blocked
             • Press ‘B’ to modify its blockers
             • Or use ‘s’ from an earlier task to add a successor that
               should come later

        • Graph Won't Open

          If ‘M-x org-gtd-show-project-graph’ doesn't work:

             • Verify you're on a project heading (not a task heading)
             • Check that the heading has ‘ORG_GTD’ property set to
               "Projects"
             • Try explicitly: ‘M-x org-gtd-show-project-graph’
             • Check for errors in ‘*Messages*’ buffer

        • Graph Shows No Tasks

          If the graph opens but shows no tasks:

             • Check if the project has subtasks (tasks should be
               subheadings under the project)
             • Verify tasks have ‘ORG_GTD_PROJECT_IDS’ property
               containing the project ID
             • Press ‘g’ to force a complete refresh
             • Check ‘*Messages*’ buffer for parsing errors

        • Task Shows Wrong State (NEXT vs TODO)

          If a task's color doesn't match its expected state:

             • Press ‘g’ to refresh (state might be stale from external
               edits)
             • Check the task's actual TODO state in the org file (press
               ‘e’ to jump there)
             • Verify dependencies are correct (press ‘i’ to inspect
               relationships)
             • Look for completed tasks that haven't been refreshed

        • Can't Modify Dependencies

          If modification commands don't work:

             • Ensure a task is selected (should see highlighted box)
             • Press ‘?’ to verify commands are available in the
               transient menu
             • Check that you're in the graph view buffer, not the org
               file buffer
             • Try ‘g’ to refresh if the graph is in an inconsistent
               state

   • See Also

        • *note Tutorial Your First Project:: for sequential project
          basics
        • *note Properties Reference: Properties Reference (Internal
          Implementation). for ‘ORG_GTD_FIRST_TASKS’,
          ‘ORG_GTD_DEPENDS_ON’, and ‘ORG_GTD_BLOCKS’ (internal
          implementation)
        • *note Commands Reference:: for all project management commands
        • *note View DSL Filter Reference:: for creating custom project
          views

   • Tickler Projects: Pausing Work You're Not Ready For

        • First Contact: Why Tickler Projects?

          You're managing 15 active projects.  Some are ready to work on
          NOW.  Others are good ideas, but wrong timing—maybe you're
          waiting for budget approval, or team availability, or just
          aren't ready to commit yet.

          Keeping them all visible in your engage view creates noise.
          You scan past 10 "someday" projects to find the 5 you can
          actually work on today.  That's cognitive load you don't need.

          *Tickler projects solve this.*  Pause a project with a review
          date.  It disappears from your engage view, your NEXT lists,
          everywhere—but preserves the complete project structure (all
          tasks, dependencies, planning work).  When the review date
          arrives or you're ready, reactivate it with one command.  The
          project springs back to life exactly as you left it.

          For GTD users managing multiple projects where some need to be
          dormant temporarily with a specific return date.

        • Black Triangle: Tickler Your First Project in 30 Seconds

          Let's tickler a project right now.

          *Step 1: Find a project you're not ready for*

          Open graph view for any project: ‘M-x
          org-gtd-show-project-graph’

          Or navigate to any project heading in your GTD file.

          *Step 2: Tickler it*

          Press ‘I’ in graph view, or run ‘M-x org-gtd-tickler’

          Enter a review date when prompted: ‘2025-06-01’

          *Step 3: Verify it's gone*

          Open your engage view: ‘C-c d e’

          The project's tasks are GONE from your NEXT list.  No clutter.

          *Step 4: Check your review date*

          The tickler project will appear in your agenda on 2025-06-01
          as a reminder to reconsider it.

          *Success!*  You've paused a project without losing any of your
          planning work.

        • Understanding Tickler: What Actually Happens

          When you tickler a project, org-gtd performs several
          operations to make it completely invisible while preserving
          state:

          *State Preservation*

          For the project heading and every task:
             • Current ‘ORG_GTD’ property → saved to ‘PREVIOUS_ORG_GTD’
               (e.g., "Projects" → "Projects")
             • Current TODO keyword → saved to ‘PREVIOUS_TODO’ property
               (e.g., "NEXT" → "NEXT")
             • ‘ORG_GTD’ property → set to "Tickler"
             • TODO keyword → cleared completely (becomes nil)

          **Why clear keywords?**  This makes tickler tasks invisible to
          all views naturally.  Your engage view shows ~(todo .
          "NEXT")~—tasks with no keywords don't match, so they disappear
          automatically.

          *Review Date Storage*

          The review date is stored in the project heading's
          ‘ORG_GTD_TIMESTAMP’ property as ‘<2025-06-01>’.  This makes
          the project appear in your org-agenda on that date, just like
          delegated items or calendar events.

          *Dependency Preservation*

          ALL dependency relationships (‘ORG_GTD_DEPENDS_ON’,
          ‘ORG_GTD_BLOCKS’) remain intact.  They're dormant—they don't
          affect anything while in tickler—but they're there.  When you
          reactivate, dependencies work exactly as before.

          *Multi-Project Tasks*

          If a task belongs to MULTIPLE projects (has multiple IDs in
          ‘ORG_GTD_PROJECT_IDS’), org-gtd uses "last active project"
          logic: the task is only incubated if the project being
          ticklered/someday'd is the *last active* project for that
          task.  An active project is one with ‘ORG_GTD: Projects’ that
          is not done or cancelled.

          This means: if Task A belongs to Project X (being ticklered)
          and Project Y (still active), Task A stays active because
          Project Y still needs it.  But if Project Y is also ticklered,
          someday, done, or cancelled, then Task A gets incubated along
          with Project X.

        • Tutorial: Managing Seasonal Projects

          Let's walk through a realistic scenario: you have annual
          projects that you only work on during specific seasons.

          *The Problem*

          You're tracking these projects:
             • "Annual Review Process" (only relevant December-January)
             • "Summer Conference Planning" (only relevant May-August)
             • "Q4 Budget Proposals" (only relevant September-November)

          It's March.  None of these are relevant, but they clutter your
          project list and NEXT tasks keep appearing in your engage
          view.

          *The Solution: Tickler Until Needed*

          In March, tickler all three:

            1. Navigate to "Summer Conference Planning"
            2. ‘M-x org-gtd-tickler’
            3. Review date: ‘2025-05-01’
            4. Repeat for other seasonal projects with appropriate dates

          Your engage view is now clean—only projects you can work on
          THIS MONTH.

          *When Review Dates Arrive*

          On May 1st, "Summer Conference Planning" appears in your
          agenda:

               Tuesday 1 May 2025
                 Summer Conference Planning (review tickler project)

          Options:
             • *Ready to activate?*  Press ‘RET’ to jump to it, then
               ‘M-x org-gtd-reactivate’
             • *Still not ready?*  Leave it in tickler, or run
               ‘org-gtd-tickler’ again with a later date

          *Reactivation Details*

          When you run ‘org-gtd-reactivate’:

            1. State restoration happens automatically:
                  • ‘PREVIOUS_ORG_GTD’ → ‘ORG_GTD’ (Tickler → Projects)
                  • ‘PREVIOUS_TODO’ → TODO keywords restored
                  • ‘ORG_GTD_TIMESTAMP’ removed (no longer in agenda)

            2. Dependency recalculation runs:
                  • ‘org-gtd-projects-fix-todo-keywords’ examines all
                    dependencies
                  • Tasks with satisfied dependencies → marked NEXT
                  • Tasks still blocked → remain TODO

            3. Project graph opens automatically:
                  • Review the project structure
                  • Verify NEXT/TODO states make sense
                  • Adjust dependencies with ‘B’ (modify blockers) or
                    ‘S’ (modify dependents)

        • Common Patterns and Scenarios

          *Pattern: "Not Now, But Someday"*

          Project ideas that might happen eventually:

               "Rewrite legacy authentication system"
               "Migrate to new CRM platform"
               "Redesign company website"

          *Strategy:*
             • Tickler with a FAR future date (2026-01-01)
             • Or use quarterly review dates (2025-07-01, 2025-10-01,
               etc.)
             • When review arrives, ask: "Is this the right time?"  If
               no, tickler again for next quarter

          *Pattern: "Waiting for External Factor"*

          Projects blocked by external dependencies:

               "Launch new product" (waiting for legal approval)
               "Office redesign" (waiting for budget committee meeting on May 15th)
               "Implement new API" (waiting for vendor release)

          *Strategy:*
             • Tickler with review date = when you expect the blocker to
               clear
             • Add note in project heading: "Tickler because: waiting
               for budget approval"
             • When reactivated, first task might be "Check if budget
               was approved"

          *Pattern: "Quarterly Batch Projects"*

          Projects you tackle in batches:

               "Review expenses" (quarterly)
               "Update documentation" (quarterly)
               "Audit security" (quarterly)

          *Strategy:*
             • After completing Q1 batch, tickler with Q2 start date
             • Review dates: 2025-04-01, 2025-07-01, 2025-10-01,
               2026-01-01
             • Consistent rhythm without manual tracking

          *Pattern: "Collaborative Project, Waiting for Team"*

          Project requires specific people who aren't available:

               "Marketing campaign redesign" (designer on vacation until June)
               "Code refactoring sprint" (waiting for team to finish current release)

          *Strategy:*
             • Tickler with return/availability date
             • In project heading, note: "Tickler: waiting for Sarah
               (back June 10th)"
             • Reactivate when team is available, project structure
               intact

        • Advanced: External Dependencies and Warnings

          *What Are External Dependencies?*

          Imagine:
             • Project A has "Task A1: Research vendor options"
             • Project B (separate project) has "Task B1: Evaluate
               vendors" that depends on Task A1 completing

          Task B1 has an *external dependency*—it depends on a task from
          a different project.

          *What Happens When Tickler'ing*

          If you tickler Project A, org-gtd warns you:

               External tasks depend on this project:
                 - Task B1: Evaluate vendors (in Project B)

               Continue tickler? (y/n)

          **Why warn?**  Tickler'ing Project A clears Task A1's TODO
          keyword.  Task B1 is still expecting Task A1 to be NEXT or
          TODO.  This creates a "dangling reference"—B1 is blocked by a
          task that doesn't exist in active work anymore.

          **Your options:**

            1. *Cancel tickler* (‘n’): Don't tickler Project A yet.
               Maybe restructure dependencies first.

            2. *Continue anyway* (‘y’): Accept that Task B1 will stay
               TODO/blocked until you reactivate Project A.  Make a note
               in Project B about this.

            3. *Remove the dependency*: Before tickler'ing, use graph
               view to remove the B1 → A1 dependency link.  Decide if B1
               should proceed independently.

          *Real-World Example*

          You're planning a conference (Project Conference) with these
          tasks:
             • Book venue
             • Invite speakers
             • Set up registration

          A separate project (Project Marketing) has:
             • "Design conference branding" → depends on "Book venue"
               (need venue details for design)

          If you tickler Project Conference (venue not booked yet,
          conference might not happen), the warning shows you that
          Marketing's branding task will be stuck.

          *Decision:* You might realize the branding task should just
          wait in Project Marketing with a note "start when conference
          is confirmed", rather than having a hard dependency.  Remove
          the link before tickler'ing.

        • Technical Details: How Tickler Works Under the Hood

          *Property-Based State Management*

          Tickler uses properties, not file movement.  The project and
          its tasks stay in the same file, same location.  Only
          properties change:

          Before tickler (Task 1 of a project):
               *** NEXT Task 1: Research options
               :PROPERTIES:
               :ID: task-1-id
               :ORG_GTD: Actions
               :ORG_GTD_PROJECT_IDS: project-id
               :ORG_GTD_DEPENDS_ON:
               :ORG_GTD_BLOCKS: task-2-id
               :END:

          After tickler:
               *** Task 1: Research options
               :PROPERTIES:
               :ID: task-1-id
               :ORG_GTD: Tickler
               :PREVIOUS_ORG_GTD: Actions
               :PREVIOUS_TODO: NEXT
               :ORG_GTD_PROJECT_IDS: project-id
               :ORG_GTD_DEPENDS_ON:
               :ORG_GTD_BLOCKS: task-2-id
               :END:

          Note:
             • TODO keyword cleared (was NEXT, now nothing)
             • ‘ORG_GTD’ changed to "Tickler"
             • Original values saved in ‘PREVIOUS_*’ properties
             • Dependencies (‘ORG_GTD_BLOCKS’) preserved unchanged

          *View Filtering Mechanism*

          Why don't tickler tasks appear in views?

          Most views filter by TODO keywords: ‘(todo . "NEXT")’, ‘(todo
          . "TODO|NEXT|WAIT")’, etc.

          Since tickler tasks have NO TODO keyword (cleared to nil),
          they don't match these filters.  Natural exclusion.

          For area-of-focus reviews that show projects, we filter: ‘(and
          (property "ORG_GTD" "Projects") (property "CATEGORY" "Work"))’

          Tickler projects have ‘(property "ORG_GTD" "Tickler")’ instead
          of "Projects", so they appear in a separate "Tickler projects"
          section.

          *Reactivation Dependency Recalculation*

          When you reactivate, here's the exact sequence:

            1. *Restore properties* (for project heading + all tasks):
                  • ‘PREVIOUS_ORG_GTD’ → ‘ORG_GTD’
                  • ‘PREVIOUS_TODO’ → TODO keyword
                  • Delete ‘PREVIOUS_*’ properties
                  • Delete ‘ORG_GTD_TIMESTAMP’

            2. *Recalculate NEXT/TODO states*:
                  • Call ‘org-gtd-projects-fix-todo-keywords’
                  • This traverses the dependency graph breadth-first
                  • For each task: if ALL dependencies are DONE/CNCL →
                    mark NEXT
                  • Otherwise → mark TODO

            3. *Open graph view* (if interactive):
                  • Shows the reactivated project visually
                  • User can verify states, adjust dependencies
                  • Immediate feedback on project structure

          **Why recalculate?**  You might have manually edited the
          project while in tickler—added tasks, changed dependencies,
          marked some DONE.  Recalculation ensures consistent state.

          *Multi-Project Task Detection*

          The check uses "last active project" logic:
               ;; A project is "active" if ORG_GTD="Projects" and not done/cancelled
               (org-gtd-project--active-p project-id)

               ;; A task is incubated only if this is its last active project
               (org-gtd-project--task-last-active-project-p task-marker current-project-id)

          If ‘ORG_GTD_PROJECT_IDS’ contains ‘"project-a project-b"’ (two
          IDs), the task belongs to both projects.  The task is only
          incubated if the current project is the last active one—i.e.,
          no other project in the task's ‘ORG_GTD_PROJECT_IDS’ is still
          active.

        • Troubleshooting Tickler

          *Tasks Still Showing After Tickler'ing Project*

          *Symptom:* You tickler'd a project, but some of its tasks
          still appear in your engage view.

          *Diagnosis:* Those tasks likely belong to multiple projects.
          Check:
            1. Navigate to the task
            2. ‘C-c C-x p’ (show properties)
            3. Look at ‘ORG_GTD_PROJECT_IDS’ value
            4. If it has multiple IDs (space-separated), the task is
               shared

          *Solution:* This is expected behavior.  Tasks are only
          incubated when the project being ticklered is the task's _last
          active_ project.  If the task still has other active projects,
          it stays active because those projects need it.  Options:
             • Tickler ALL active projects the task belongs to (task
               will then be tickler'd)
             • Remove the task from one of the projects first
             • Accept that the task stays visible (it's genuinely active
               in another project)

          *Tickler Project Doesn't Appear on Review Date*

          *Symptom:* Review date arrived (e.g., June 1st), but the
          project doesn't show in your agenda.

          *Diagnosis:*
            1. Navigate to the project heading
            2. Check for ‘ORG_GTD_TIMESTAMP’ property
            3. Verify format is ‘<2025-06-01>’ (angle brackets,
               YYYY-MM-DD)
            4. Check your org-agenda-files includes the GTD file

          *Solution:*
             • If property is missing: tickler again with a date
             • If format is wrong: manually fix to ‘<YYYY-MM-DD>’
             • If file not in agenda: ‘M-x org-agenda-file-to-front’
               while in the GTD file

          *Reactivated Project Has Wrong NEXT/TODO States*

          *Symptom:* After reactivating, tasks that should be NEXT are
          showing as TODO, or vice versa.

          *Diagnosis:* Open graph view (‘M-x
          org-gtd-show-project-graph’):
             • Trace arrows (dependencies)
             • Check if dependencies are actually DONE
             • Look for tasks with cleared keywords that should have
               keywords

          *Solution:*
             • Press ‘g’ to refresh and recalculate states
             • If recalculation doesn't fix it: dependencies might be
               incorrect
             • Use ‘B’ to modify blockers, then ‘g’ to recalculate

          *Can't Reactivate: "Not Tickler" Error*

          *Symptom:* Running ‘org-gtd-reactivate’ gives error: "Item at
          point is not tickler"

          *Diagnosis:* Check the ‘ORG_GTD’ property:
            1. ‘C-c C-x p’ to show properties
            2. Look for ‘ORG_GTD’ value
            3. Should be "Tickler"

          *Solution:*
             • If ‘ORG_GTD’ is something else (e.g., "Projects"): it's
               not in tickler, nothing to reactivate
             • If manually edited: set ‘ORG_GTD’ back to "Tickler" or
               just manually restore the state
             • If ‘PREVIOUS_*’ properties are missing: you'll need to
               manually set states

        • See Also

             • *note Commands Reference:: for ‘org-gtd-tickler’ and
               ‘org-gtd-reactivate’ full command details
             • *note Tutorial Your First Project:: for project basics
               before tickler'ing
             • *note Why Visual Project Management?: First Contact Why
               Visual Project Management?. for understanding project
               structure
             • *note Properties Reference: Properties Reference
               (Internal Implementation). for ‘PREVIOUS_ORG_GTD’,
               ‘PREVIOUS_TODO’, ‘ORG_GTD_TIMESTAMP’ details

   • Project Progress Cookies: See Your Progress at a Glance

        • First Contact: What Are Progress Cookies?

          Progress cookies show how far along your project is:
          ‘[3/7][42%]’ means 3 of 7 tasks done.

          They appear directly on project headings, so you can scan your
          project list and instantly know which projects are nearly
          complete, which are just starting, and which might need
          attention.

          *Who needs this?*  Anyone managing multiple projects who wants
          quick visual feedback without opening each project to count
          tasks.

        • Black Triangle: See Progress in 30 Seconds

          Your projects already have progress cookies—they're enabled by
          default.

            1. Open your engage view: ‘C-c d e’
            2. Find any project task
            3. Press ‘RET’ to jump to the project heading

          You'll see something like:

               * PROJ Buy a house [0/5][0%]                      :home:

          That's it.  The ‘[0/5][0%]’ shows 0 of 5 tasks completed.

        • Tutorial: Watch Cookies Update Automatically

          Let's see progress cookies in action:

            1. *Find a project with tasks:*
                  • Open engage view: ‘C-c d e’
                  • Navigate to a project task, press ‘RET’ to go to the
                    project heading
                  • Note the current cookie: ‘[0/3][0%]’ (or similar)

            2. *Complete a task:*
                  • Find a NEXT task in that project
                  • Mark it done: ‘C-c C-t DONE’ (or cycle to DONE)

            3. *Check the project heading:*
                  • Scroll up to the project heading
                  • The cookie updated: ‘[1/3][33%]’

          No manual refresh needed.  Complete tasks, cookies update
          automatically.

        • Understanding How Cookies Work

          **What gets counted?**

          Progress cookies count all tasks linked to the project via
          ‘ORG_GTD_PROJECT_IDS’.  This is different from org-mode's
          built-in ‘[/]’ cookies which only count direct children.

          Why does this matter?  In org-gtd v4, projects are DAGs
          (directed acyclic graphs)—tasks can live anywhere in your GTD
          files and link to projects by ID.  The cookie counts ALL
          linked tasks, regardless of where they're located in your
          files.

          **When do cookies update?**

             • *Task state changes:* Complete a task → cookie updates
               immediately
             • *Project creation:* New projects get cookies
               automatically
             • *Manual refresh:* ‘M-x
               org-gtd-project-update-all-cookies’ refreshes everything
             • *Fix TODO keywords:* ‘M-x
               org-gtd-projects-fix-all-todo-keywords’ also refreshes
               cookies

        • Configuring Cookie Position

          Control where cookies appear with
          ‘org-gtd-project-progress-cookie-position’:

               ;; At end of heading, before tags (default)
               (setq org-gtd-project-progress-cookie-position 'end)

               ;; After TODO keyword, before title
               (setq org-gtd-project-progress-cookie-position 'start)

               ;; Disable cookies entirely
               (setq org-gtd-project-progress-cookie-position nil)

          Visual comparison:

               ;; 'end (default):
               * PROJ Buy a house [3/7][42%]                    :home:

               ;; 'start:
               * PROJ [3/7][42%] Buy a house                    :home:

               ;; nil:
               * PROJ Buy a house                               :home:

        • Common Scenarios

          **Cookies look wrong after external edits**

          You edited tasks outside org-gtd (mobile app, manual edit) and
          cookies don't match reality.

          *Fix:* ‘M-x org-gtd-project-update-all-cookies’

          This scans all projects and recalculates from scratch.

          **Want to disable cookies for performance**

          If you have hundreds of projects and notice slowness:

               (setq org-gtd-project-progress-cookie-position nil)

          Cookies won't update or display.

          **Cookies showing 0/0**

          This means no tasks are linked to the project.  Either:
             • The project has no tasks yet (add some)
             • Tasks don't have ‘ORG_GTD_PROJECT_IDS’ pointing to this
               project (check properties)

        • Technical Reference

          **Format:** ‘[completed/total][percent%]’

          **Calculation:** Scans all headings with ‘ORG_GTD_PROJECT_IDS’
          matching the project's ID.  Counts tasks with TODO keyword in
          ‘org-done-keywords’ as completed.

          **Storage:** Actual text on the heading (not computed at
          display time).  This means cookies persist and are visible
          even in non-Emacs editors.

          **Hook:** ‘org-after-todo-state-change-hook’ triggers
          recalculation when task states change.

          **Related commands:**
          ‘org-gtd-project-update-all-cookies’
               Refresh all project cookies
          ‘org-gtd-projects-fix-all-todo-keywords’
               Fixes keywords AND refreshes cookies

          *See also:* *note org-gtd-project-progress-cookie-position::
          in Configuration Variables Reference.

   • Cleaning up / archiving completed work

     Doing this without user intervention is tricky, as it makes undoing
     actions more complicated.  As such, Org GTD provides a function
     that will go through the ‘org-gtd-directory’ files, find the
     headings that belong to Org GTD (see *note Refiling to the
     appropriate area::), and archive the finished items.

     The variable ‘org-gtd-archive-location’ points to a *function* that
     returns a string matching the ‘org-archive-location’ definition.
     It is a function in order to allow the filename to be dynamic.

     The function to archive everything is ‘M-x
     org-gtd-archive-completed-items’.

   • Commands you can call on org-agenda

     Since Org provides the agenda, it is a convenient base of
     operations for interacting with things that come up through
     ‘org-gtd-engage’.

     Here are the actions available to you:

     ‘M-x org-gtd-delegate-agenda-item’
          When the point is on an action, this will properly delegate
          the action to someone else.
     ‘M-x org-gtd-project-cancel-from-agenda’
          When the point is on a project action, this command will
          prompt for confirmation and then cancel the remaining actions
          in the project.
     ‘M-x org-gtd-clarify-agenda-item’
          If you would like to clarify and organize an item through the
          agenda view, for whatever reason, this is your entry point.

   • Defining your own agenda views

     You can define your own agenda views by defining functions with
     custom agenda commands.  As long as you have ‘org-gtd-directory’ in
     your ‘org-agenda-files’ (required for org-gtd to work), your views
     will include GTD items automatically.

          (defun my-agenda ()
            (let ((org-agenda-custom-commands '(your-definition-here)))
              (org-agenda nil "x")))

     Where ‘x’ is whatever your defined key is.

     *See also*: For a much easier way to create custom views, see *note
     View DSL Filter Reference::, which provides a declarative language
     for defining views without writing skip functions.

   • Adding your own hooks when organizing

     Adding useful metadata to the tasks allows you to enhance the
     agenda view to make it more useful to you, whether it be effort,
     tags, priority, or any other amount of information you might like.

     This being said, different types of tasks or items are not even
     created equal.  For instance, there may be metadata you want to add
     to a project heading but not its tasks, or to a calendar item and
     not to a trash item.

     Org GTD therefore provides a helper function,
     ‘org-gtd-organize-type-member-p’, which you can use when creating
     your own hooks.  The function takes one argument, a list of types
     (provided in the function's documentation).  When called as part of
     a hook, this function will check a buffer-local variable called
     ‘org-gtd--organize-type’, managed by Org GTD, to determine
     truthiness.

     For an example, see the source code for
     ‘org-gtd-areas-of-focus--set’, which will not run if the task being
     organized is a project task, trash, knowledge, or a quick action.

     *See also*: For complete documentation on the hooks framework,
     including many examples and best practices, see *note Hooks
     Framework Reference::.


File: org-gtd.info,  Node: Automating through emacs,  Prev: Working with Projects (Advanced),  Up: Using Org GTD

1.4.5 Automating through emacs
------------------------------

There's now a few functions you can use when you are doing work within
emacs and would like GTD to track something for you as a result:
   • ‘org-gtd-habit-create’
   • ‘org-gtd-calendar-create’
   • ‘org-gtd-delegate-create’
   • ‘org-gtd-tickler-create’
   • ‘org-gtd-someday-create’
   • ‘org-gtd-single-action-create’

   See the documentation for each, but suffice it to say they all take,
at the very least, a string that will be used as the text part of the
org heading that gets stored in org-gtd.

   For instance, one way this could work:

     (defun org-gtd-email-reminder ()
       (let ((topic (message-fetch-field "subject"))
             (delegated-to (message-fetch-field "to"))
             (reminder-date (org-read-date nil nil "+3d")))
         (org-gtd-delegate-create (format "Reminder: %s" topic)
                                  delegated-to
                                  reminder-date)))

     (add-hook 'message-send-hook 'org-gtd-email-reminder)

   *See also*: *note Commands Reference:: for complete documentation of
all programmatic creation commands.


File: org-gtd.info,  Node: Reference,  Next: Extending org-gtd,  Prev: Using Org GTD,  Up: Summary

1.5 Reference
=============

This section provides complete reference documentation for all org-gtd
configuration variables, commands, properties, and advanced features.
Use this section when you need to look up specific details about a
configuration option, command, or property.

   *Quick navigation*:
   • *note Configuration Variables Reference:: - All customization
     options
   • *note Commands Reference:: - All interactive commands organized by
     workflow step
   • *note Properties Reference: Properties Reference (Internal
     Implementation). - All org properties used by org-gtd
   • *note View DSL Filter Reference:: - Complete guide to creating
     custom views
   • *note Hooks Framework Reference:: - Complete guide to customization
     hooks

   For learning how to use org-gtd, start with *note Getting Started
with Org GTD:: and *note Using Org GTD::.

* Menu:

* Configuration Variables Reference:: All customization variables explained
* Commands Reference::           All interactive commands explained
* Properties Reference (Internal Implementation):: All org properties used by org-gtd
* Troubleshooting Projects::     How to fix project dependency problems
* View DSL Filter Reference::    Complete reference for the View DSL
* Hooks Framework Reference::    Complete guide to customization hooks


File: org-gtd.info,  Node: Configuration Variables Reference,  Next: Commands Reference,  Up: Reference

1.5.1 Configuration Variables Reference
---------------------------------------

These variables control how org-gtd behaves.  All can be customized via
‘M-x customize-group RET org-gtd’.

   • Required Configuration

        • ‘org-todo-keywords’ (org-mode variable)

          *Type*: List of keyword sequences

          *Default*: Varies by org-mode installation

          *Description*: Defines TODO keyword sequences for org-mode.
          All GTD keywords must be in the *same sequence*.

          *Required format*:
               (setq org-todo-keywords
                     '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

          The ‘|’ separator marks done states (right side) from active
          states (left side).

          *Org-mode keyword options are supported*: You can use
          org-mode's standard keyword syntax with fast access keys and
          logging options (e.g., ‘"TODO(t)"’, ‘"DONE(d!)"’,
          ‘"WAIT(w@/!)"’).  Org-gtd only looks at the base keyword
          string, so these are equivalent:

               ;; Basic
               '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL"))

               ;; With fast access keys and logging
               '((sequence "TODO(t)" "NEXT(n)" "WAIT(w@/!)" "|" "DONE(d!)" "CNCL(c)"))

        • ‘org-gtd-keyword-mapping’

          *Type*: Alist mapping GTD states to keyword strings

          *Default*:
               '((todo . "TODO")
                 (next . "NEXT")
                 (wait . "WAIT")
                 (canceled . "CNCL"))

          *Description*: Maps GTD semantic states to your chosen TODO
          keywords.

          *Required keys*:
          ‘todo’
               Tasks not ready to be acted upon
          ‘next’
               Tasks ready to act on immediately
          ‘wait’
               Tasks blocked or delegated to someone else
          ‘done’
               Tasks successfully completed
          ‘canceled’
               Tasks that won't be completed

          *Example*: Using custom keywords:
               (setq org-todo-keywords
                     '((sequence "TASK" "DOING" "BLOCKED" "|" "COMPLETE" "CANCELLED")))

               (setq org-gtd-keyword-mapping
                     '((todo . "TASK")
                       (next . "DOING")
                       (wait . "BLOCKED")
                       (done . "COMPLETE")
                       (canceled . "CANCELLED")))

   • Directory and File Configuration

        • ‘org-gtd-directory’

          *Type*: String (directory path)

          *Default*: ‘"~/gtd/"’

          *Description*: Directory where org-gtd keeps all its files.

          org-gtd creates these files in this directory:
             • ‘inbox.org’ - Capture target (created on first capture)
             • ‘org-gtd-tasks.org’ - Main GTD file containing all
               organized items

          All GTD categories (Actions, Projects, Calendar, Tickler,
          Delegated, etc.)  are stored as top-level headings within
          ‘org-gtd-tasks.org’, not as separate files.  These headings
          are created automatically when you first refile an item to
          that category.

          *Example*:
               (setq org-gtd-directory "~/my-gtd/")

          *Note*: Make sure to add this directory to ‘org-agenda-files’
          after org-gtd loads:
               (with-eval-after-load 'org-gtd
                 (setq org-agenda-files (list org-gtd-directory)))

          For ‘use-package’, put this in the ‘:config’ section.

        • ‘org-gtd-additional-inbox-files’

          *Type*: List of file paths

          *Default*: ‘nil’

          *Description*: Additional inbox files to process after the
          main inbox.

          When you call ‘org-gtd-process-inbox’, it first processes all
          items in the main inbox (‘inbox.org’).  After the main inbox
          is empty, it continues processing items from these additional
          files in order.

          This is useful when you capture items from multiple sources:
             • Mobile apps that sync to a separate file
             • Email-to-org workflows
             • Context-specific inboxes (work, personal)

          *Example*:
               (setq org-gtd-additional-inbox-files
                     '("~/gtd/mobile-inbox.org"
                       "~/gtd/email-inbox.org"))

          *Note*: Each file should contain org headings at the top
          level, just like the main inbox.

        • ‘org-gtd-horizons-file’

          *Type*: String (filename)

          *Default*: ‘"horizons.org"’

          *Description*: Name of file (in ‘org-gtd-directory’)
          containing your GTD horizons (long-term goals, areas of focus,
          purpose).

          This file can be displayed during clarification for context.

          *Example*:
               (setq org-gtd-horizons-file "my-horizons.org")

   • Capture Configuration

        • ‘org-gtd-capture-templates’

          *Type*: List of org-capture template specifications

          *Default*:
               '(("i" "Inbox"
                  entry  (file ,#'org-gtd-inbox-path)
                  "* %?\n%U\n\n  %i"
                  :kill-buffer t)
                 ("l" "Inbox with link"
                  entry  (file ,#'org-gtd-inbox-path)
                  "* %?\n%U\n\n  %i\n  %a"
                  :kill-buffer t))

          *Description*: Capture templates specific to org-gtd inbox.

          *Constraints* (must be satisfied for org-gtd to work
          correctly):
            1. Template string must start with ‘"* "’ (asterisk + space
               for org heading)
            2. Entry type must be: ‘entry (file ,#'org-gtd-inbox-path)’

          *Example*: Adding a custom template:
               (setq org-gtd-capture-templates
                     '(("i" "Inbox"
                        entry (file ,#'org-gtd-inbox-path)
                        "* %?\n%U\n\n  %i"
                        :kill-buffer t)
                       ("m" "Meeting note"
                        entry (file ,#'org-gtd-inbox-path)
                        "* Meeting: %?\n%U\n\nAttendees:\n\nNotes:\n"
                        :kill-buffer t)))

   • Organize and Process Configuration

        • ‘org-gtd-organize-hooks’

          *Type*: List of functions

          *Default*: ‘'(org-set-tags-command)’

          *Description*: Functions run when organizing each item.  Each
          function can add metadata (tags, properties, etc.)  to the
          item being organized.

          The default value prompts for tags.  Built-in options:
          ‘org-set-tags-command’
               Prompt for tags (default)
          ‘org-gtd-set-area-of-focus’
               Prompt for area of focus
          Custom functions
               Functions you write yourself

          *Example*: Add effort estimation and area of focus:
               (defun my-add-effort ()
                 "Prompt for effort when organizing."
                 (when (org-gtd-organize-type-member-p '(single-action project-heading))
                   (org-set-effort)))

               (setq org-gtd-organize-hooks
                     '(org-set-tags-command
                       org-gtd-set-area-of-focus
                       my-add-effort))

          *Helper function*: ‘org-gtd-organize-type-member-p’
             • Takes a list of item types to check against
             • Returns t if current item matches one of the types
             • Available types: ‘single-action’, ‘project-heading’,
               ‘project-task’, ‘calendar’, ‘delegated’, ‘tickler’,
               ‘someday’, ‘habit’, ‘knowledge’, ‘quick-action’, ‘trash’,
               ‘everything’

        • ‘org-gtd-save-after-organize’

          *Type*: Boolean

          *Default*: ‘nil’

          *Description*: If non-nil, save all modified buffers after
          each organize step.

          Useful if you want automatic saves during inbox processing.

          *Example*:
               (setq org-gtd-save-after-organize t)

        • ‘org-gtd-refile-to-any-target’ (deprecated)

          *Type*: Boolean

          *Default*: ‘t’

          *Deprecated*: As of 4.0.0.  Use
          ‘org-gtd-refile-prompt-for-types’ instead.

          *Description*: Control refile behavior when organizing items.
          This variable is deprecated and will show a warning when used.

             • When ‘t’: org-gtd will refile to the first target it
               finds without prompting (deprecated behavior)
             • When ‘nil’: org-gtd consults
               ‘org-gtd-refile-prompt-for-types’ to decide per item type

          *Migration*: To migrate to the new system:

               ;; Step 1: Set the deprecated variable to nil (required)
               ;; This enables per-type control via org-gtd-refile-prompt-for-types
               (setq org-gtd-refile-to-any-target nil)

               ;; Step 2 (optional): Customize which types prompt
               ;; The default prompts for most types except quick-action, knowledge, trash
               ;; Only change this if you want different behavior:
               ;; (setq org-gtd-refile-prompt-for-types '(project-heading project-task))

          See *note Controlling Refile Prompts by Item Type:: for the
          new approach.

        • ‘org-gtd-refile-prompt-for-types’

          *Type*: List of symbols

          *Default*: ‘(single-action project-heading project-task
          calendar someday delegated tickler habit)’

          *Description*: List of GTD item types that should prompt for
          refile target selection when organizing.

             • Types in the list prompt user to choose from available
               refile targets
             • Types *not* in the list auto-refile to the first
               available target
             • Only consulted when ‘org-gtd-refile-to-any-target’ is
               ‘nil’

          *Valid type symbols:* ‘single-action’, ‘project-heading’,
          ‘project-task’, ‘calendar’, ‘someday’, ‘delegated’, ‘tickler’,
          ‘habit’, ‘knowledge’, ‘quick-action’, ‘trash’

          *Example*: Only prompt for projects, auto-refile everything
          else:

               (setq org-gtd-refile-prompt-for-types '(project-heading project-task))

          *Example*: Add knowledge items to prompt list (they
          auto-refile by default):

               (setq org-gtd-refile-prompt-for-types
                     '(single-action project-heading project-task calendar
                       someday delegated tickler habit knowledge))

          See *note Controlling Refile Prompts by Item Type:: for
          detailed examples.

   • Mode-Line Configuration

        • ‘org-gtd-mode-update-interval’

          *Type*: Integer (seconds) or nil

          *Default*: ‘60’

          *Description*: Seconds between automatic inbox count refreshes
          when ‘org-gtd-mode’ is enabled.

          The mode-line lighter (e.g., ‘GTD[5]’) updates automatically
          when Emacs redraws the mode-line.  This setting controls an
          additional periodic refresh to catch external file changes
          (like mobile app syncs).

          Values:
          Integer
               Refresh every N seconds
          ‘nil’
               Disable periodic refresh (count still updates on
               mode-line redraw)

          *Example*: Refresh every 30 seconds:
               (setq org-gtd-mode-update-interval 30)

          *Example*: Disable periodic refresh:
               (setq org-gtd-mode-update-interval nil)

        • ‘org-gtd-mode-lighter-display’

          *Type*: Symbol

          *Default*: ‘'always’

          *Description*: Controls when the GTD lighter appears in the
          mode-line.

          Values:
          ‘'always’
               Always show the lighter (e.g., ‘GTD[0]’, ‘GTD[5]’)
          ‘'never’
               Never show the lighter
          ‘'when-non-zero’
               Only show when inbox has items

          *Example*: Hide lighter when inbox is empty:
               (setq org-gtd-mode-lighter-display 'when-non-zero)

   • Clarification Configuration

        • ‘org-gtd-clarify-show-horizons’

          *Type*: Symbol or nil

          *Default*: ‘nil’

          *Description*: Whether to show horizons file during
          clarification.

          Values:
          ‘nil’
               Don't show horizons by default
          ‘'top’
               Show horizons window at top
          ‘'bottom’
               Show horizons window at bottom
          ‘'left’
               Show horizons window on left
          ‘'right’
               Show horizons window on right

          *Example*:
               (setq org-gtd-clarify-show-horizons 'right)

          *Related command*: ‘org-gtd-clarify-toggle-horizons-window’ to
          toggle visibility during clarification.

        • ‘org-gtd-clarify-show-organize-help’

          *Type*: Symbol or nil

          *Default*: ‘nil’

          *Description*: Whether to show the organize types help buffer
          during clarification.  This buffer displays all GTD item types
          with their keyboard shortcuts and brief descriptions, helping
          you decide how to categorize an item.

          Values:
          ‘nil’
               Don't show by default (toggle with command)
          ‘'top’
               Show help window at top
          ‘'bottom’
               Show help window at bottom
          ‘'left’
               Show help window on left
          ‘'right’
               Show help window on right

          *Example*:
               (setq org-gtd-clarify-show-organize-help 'right)

          *Related command*: ‘org-gtd-clarify-toggle-organize-help’ to
          toggle visibility during clarification.

          *Note*: If both this and ‘org-gtd-clarify-show-horizons’ are
          set to the same side, Emacs will stack the windows vertically
          in that side area.

        • ‘org-gtd-clarify-display-helper-buffer’

          *Type*: Boolean

          *Default*: ‘nil’

          *Description*: If non-nil, display project dependencies helper
          window when clarifying projects.

          When enabled, shows a live view of task relationships in a
          side window when there are multiple tasks in the WIP buffer.

          Useful for:
             • Understanding complex dependency graphs
             • Spotting cycles before they cause problems
             • Planning parallel execution paths

          *Example*:
               (setq org-gtd-clarify-display-helper-buffer t)

        • ‘org-gtd-clarify-project-templates’

          *Type*: Alist of (name .  template) strings

          *Default*: ‘nil’

          *Description*: Pre-defined project templates for common
          project types.

          Each entry is a pair of (template-name .  template-tasks)
          where template-tasks is a string of org headings to insert.

          *Example*:
               (setq org-gtd-clarify-project-templates
                     '(("Blog Post" . "** Research topic\n** Write draft\n** Edit\n** Add images\n** Publish")
                       ("Code Feature" . "** Design API\n** Write tests\n** Implement feature\n** Code review\n** Merge")))

          *Entering newlines in templates*: When setting this variable
          in your configuration file, use ‘\n’ for newlines as shown
          above.  If entering template strings interactively (e.g., via
          ‘M-x customize-variable’ or in the minibuffer), use ‘C-q C-j’
          to insert a literal newline character.  This works on all
          platforms including Windows.

          Use ‘org-gtd-clarify-project-insert-template’ during
          clarification to insert a template.

        • ‘org-gtd-clarify-duplicate-queue-position’

          *Type*: Symbol

          *Default*: ‘'bottom’

          *Description*: Position for the duplicate queue window during
          clarification.

          When you create duplicates during clarification, a side window
          appears showing pending duplicates.  This variable controls
          where that window appears.

          Values:
          ‘'top’
               Show queue window at top
          ‘'bottom’
               Show queue window at bottom
          ‘'left’
               Show queue window on left
          ‘'right’
               Show queue window on right

          *Example*:
               (setq org-gtd-clarify-duplicate-queue-position 'right)

          *See also*: *note Duplicating items during clarification::

   • Areas of Focus Configuration

        • ‘org-gtd-areas-of-focus’

          *Type*: List of strings

          *Default*: ‘'("Home" "Health" "Family" "Career")’

          *Description*: Your areas of focus (GTD Horizon 2) - the major
          areas in your life where you don't want to drop balls.

          Used when:
             • Adding area of focus to items (via
               ‘org-gtd-set-area-of-focus’ hook)
             • Reviewing specific areas with
               ‘org-gtd-reflect-area-of-focus’

          *Example*:
               (setq org-gtd-areas-of-focus
                     '("Work" "Home" "Health" "Learning" "Relationships" "Finance"))

   • View Prefix Configuration

        • ‘org-gtd-prefix-width’

          *Type*: Integer

          *Default*: ‘12’

          *Description*: Default width for the prefix column in org-gtd
          views.

          The prefix shows context information (project name, area of
          focus, etc.)  on the left side of each task.  This variable
          sets the default width used when no explicit ‘prefix-width’ is
          specified in a view spec.

          Long values are truncated with
          ‘org-gtd-agenda-truncate-ellipsis’ (default "…").  Short
          values are padded with spaces.

          *Example*: Increase space for longer project names:
               (setq org-gtd-prefix-width 20)

          *Note*: You can also set ‘prefix-width’ per-view in the View
          DSL.  See *note Prefix DSL: Prefix DSL Customizing the Task
          Prefix Column.

          *Backward compatibility*: The old name
          ‘org-gtd-engage-prefix-width’ still works but is deprecated.

        • ‘org-gtd-agenda-truncate-ellipsis’

          *Type*: String

          *Default*: ‘"…"’

          *Description*: String appended when truncating long text in
          agenda prefixes.

          The default ellipsis character (‘…’) doesn't have consistent
          width across all fonts.  Some fonts (like Iosevka) display it
          wider than one character, causing agenda items to misalign.

          *Example*: Use ASCII dots for consistent alignment:
               (setq org-gtd-agenda-truncate-ellipsis "...")

          *Example*: Use a Braille character (works well in some fonts):
               (setq org-gtd-agenda-truncate-ellipsis "⣀")

          *See also*: ‘org-gtd-prefix-width’ for controlling prefix
          column width.

   • Archive Configuration

        • ‘org-gtd-archive-location’

          *Type*: Function (zero arguments, returns string) or ‘nil’

          *Default*: ‘#'org-gtd-archive-location-func’

          *Description*: Archive location for org-gtd, or ‘nil’ to use
          ‘org-archive-location’.

          When ‘nil’, org-gtd uses org-mode's standard
          ‘org-archive-location’ variable.  This allows you to use your
          existing org-mode archive configuration with org-gtd.

          When a function, calls it to get the archive location string.
          The returned string must match ‘org-archive-location’ format.

          Default function generates: ‘gtd_archive_YYYY.org::datetree/’
          (year-based archive files in ‘org-gtd-directory’).

          *Example*: Use org-mode's standard archive location:
               ;; Respect your org-archive-location setting
               (setq org-gtd-archive-location nil)
               ;; Configure org-mode's archive as usual
               (setq org-archive-location "archive.org::* Archived")

          *Example*: Archive to a single file:
               (defun my-archive-location ()
                 "Archive to a single file."
                 "archive.org::")

               (setq org-gtd-archive-location #'my-archive-location)

          *Example*: Archive to month-based files:
               (defun my-monthly-archive ()
                 "Archive to month-based files."
                 (format "archive-%s.org::datetree/"
                         (format-time-string "%Y-%m")))

               (setq org-gtd-archive-location #'my-monthly-archive)

   • Missed Engagements Review Configuration

        • ‘org-gtd-reflect-missed-custom-views’

          *Type*: List of GTD view specifications

          *Default*: ‘nil’

          *Purpose*: Create custom views to find specific types of
          missed engagements (e.g., only work-related items, only
          specific areas of focus).

          Think of this like creating saved searches.  Instead of seeing
          ALL missed items, you can create views that show only the ones
          relevant to a specific context.

          *When to use*: If you have multiple areas of focus (Work,
          Home, Hobbies) and want to review each separately.

          *Example - Area-Specific Reviews*:
               (setq org-gtd-reflect-missed-custom-views
                     '(((name . "Overdue Work Items")
                        (area-of-focus . "Work")
                        (deadline . past))
                       ((name . "Missed Home Appointments")
                        (area-of-focus . "Home")
                        (type . calendar)
                        (when . past))))

          After configuring, run ‘M-x
          org-gtd-reflect-missed-with-custom’ to see all standard views
          plus your custom ones.

          *Backward compatibility*: The old variable name
          ‘org-gtd-oops-custom-views’ still works but will be removed in
          a future version.

   • Advanced Item Configuration

        • ‘org-gtd-user-types’

          *Type*: Alist

          *Default*: ‘'()’

          *Description*: Customize property prompts and input methods
          for built-in GTD types.

          This alist allows you to override how org-gtd prompts for
          properties when organizing items.  You can customize existing
          types but cannot add new ones.

          Each entry is ‘(TYPE-NAME . PLIST)’ where TYPE-NAME must be
          one of: ‘next-action’, ‘delegated’, ‘calendar’, ‘tickler’,
          ‘someday’, ‘project’, ‘habit’, ‘reference’, ‘trash’,
          ‘quick-action’.

          *Property attributes you can set:*

          Attribute         Description
          ---------------------------------------------------------------------------
          ‘:prompt’         The prompt string shown to the user
          ‘:input-fn’       Custom function for input (overrides default prompt)
          ‘:default’        Default value (skips prompting if set)
          ‘:type’           Input type: ‘text’, ‘timestamp’, ‘repeating-timestamp’
          ‘:required’       Whether the property is required (‘t’ or ‘nil’)
          ‘:org-property’   The org-mode property name (string)

          *Example: Integrating Contact Managers with Delegation*

          BBDB and EBDB are Emacs contact management packages.  You can
          configure org-gtd to use completion from your contacts
          database when delegating tasks.

          For EBDB integration:
               ;; Define function to complete from EBDB contacts
               (defun my/ebdb-completing-read (prompt)
                 "Read a contact name from EBDB with completion."
                 (completing-read prompt
                                  (mapcar (lambda (rec) (ebdb-record-name-string rec))
                                          (ebdb-records))
                                  nil t))

               ;; Configure delegation to use EBDB completion
               (setq org-gtd-user-types
                     '((delegated
                        :properties
                        ((:who :org-property "DELEGATED_TO" :type text :required t
                               :prompt "Delegate to"
                               :input-fn my/ebdb-completing-read)))))

          For BBDB integration, use ‘bbdb-records’ and
          ‘bbdb-record-name’ instead:
               (defun my/bbdb-completing-read (prompt)
                 "Read a contact name from BBDB with completion."
                 (completing-read prompt
                                  (mapcar #'bbdb-record-name (bbdb-records))
                                  nil t))

          This pattern works for any completion source (org-contacts,
          custom databases, etc.).

          *Example: Custom prompt text*

          Change the default prompts without changing input behavior:
               (setq org-gtd-user-types
                     '((delegated
                        :properties
                        ((:who :org-property "DELEGATED_TO" :type text :required t
                               :prompt "Assign to team member")
                         (:when :org-property "ORG_GTD_TIMESTAMP" :type timestamp :required t
                                :prompt "Follow-up date")))))

   • Agenda Display Configuration

     These variables control how properties are displayed in org-agenda
     views.  When you run ‘org-gtd-engage’ or other agenda commands,
     these settings determine what additional information appears
     alongside each task.

        • ‘org-gtd-agenda-property-list’

          *Type*: List of strings

          *Default*: ‘'("LOCATION")’

          *Description*: Properties to display in agenda views.

          When a task has any of these properties set, the value appears
          in the agenda line.  Useful for showing context like location,
          delegated person, or custom metadata.

          *Example*:
               ;; Show location and who tasks are delegated to
               (setq org-gtd-agenda-property-list '("LOCATION" "DELEGATED_TO"))

        • ‘org-gtd-agenda-property-position’

          *Type*: Symbol

          *Default*: ‘'where-it-fits’

          *Description*: Where properties appear relative to the agenda
          line.

          Values:
          ‘'same-line’
               On the same line, starting at
               ‘org-gtd-agenda-property-column’
          ‘'next-line’
               On the line below the task
          ‘'where-it-fits’
               Same line if it fits in the window, otherwise next line
               (default)

          *Example*:
               (setq org-gtd-agenda-property-position 'next-line)

        • ‘org-gtd-agenda-property-column’

          *Type*: Integer

          *Default*: ‘60’

          *Description*: Column position where properties start when
          using ‘'same-line’ or ‘'where-it-fits’ position.

          Increase this if your task descriptions are long; decrease if
          you want properties closer to the task text.

          *Example*:
               (setq org-gtd-agenda-property-column 50)

        • ‘org-gtd-agenda-property-separator’

          *Type*: String

          *Default*: ‘"|"’

          *Description*: Separator between multiple property values when
          a task has more than one property from
          ‘org-gtd-agenda-property-list’.

          *Example*:
               (setq org-gtd-agenda-property-separator " · ")

   • Graph View Configuration

     These variables control the project graph visualization feature.

        • ‘org-gtd-graph-render-mode’

          *Type*: Symbol

          *Default*: ‘'svg’

          *Description*: Default rendering mode for project dependency
          graphs.

          Values:
          ‘'svg’
               High-quality graphical rendering (requires GUI Emacs)
          ‘'ascii’
               Text-based rendering using box-drawing characters (works
               in terminal)

          You can toggle between modes in any graph buffer by pressing
          ‘v’.

          *Example*:
               ;; Use ASCII mode by default (good for terminal users)
               (setq org-gtd-graph-render-mode 'ascii)

          *See also*: *note Graph Rendering Modes:: for detailed
          comparison.

        • ‘org-gtd-graph-ui-split-ratio’

          *Type*: Float (0.0 to 1.0)

          *Default*: ‘0.7’

          *Description*: Width ratio for the graph window when showing
          project graphs.

          The graph view displays two panels: the dependency graph and a
          details panel showing the selected task.  This ratio controls
          how much horizontal space the graph takes.

             • ‘0.7’ means the graph takes 70% of width, details take
               30% (default)
             • ‘0.5’ would give equal space to both
             • ‘0.8’ would give more space to the graph

          *Example*:
               ;; Give more space to the details panel
               (setq org-gtd-graph-ui-split-ratio 0.6)

        • ‘org-gtd-graph-sibling-mode’

          *Type*: Symbol

          *Default*: ‘'any-same-blocker’

          *Description*: How to determine sibling tasks for TAB/S-TAB
          navigation in graph view.

          When you press TAB or S-TAB in graph view, you move between
          "sibling" tasks.  This variable controls what counts as a
          sibling:

          Values:
          ‘'any-same-blocker’
               Tasks sharing at least one blocker (default).  Two tasks
               are siblings if they have any blocker in common.  This
               groups tasks that are conceptually related through shared
               prerequisites.
          ‘'all-same-blockers’
               Tasks with exactly the same set of blockers.  Two tasks
               are siblings only if their blocker sets are identical.
               This is stricter and shows only tasks that are truly
               parallel alternatives.
          ‘'dag-level’
               Tasks at the same depth in the dependency graph.  Two
               tasks are siblings if they have the same layer number,
               regardless of their actual blockers.  This gives a
               visual/structural grouping.

          *Example*:
               ;; Default: share any blocker
               (setq org-gtd-graph-sibling-mode 'any-same-blocker)

               ;; Strict: exact same blockers only
               (setq org-gtd-graph-sibling-mode 'all-same-blockers)

               ;; Structural: same depth in graph
               (setq org-gtd-graph-sibling-mode 'dag-level)

          *When to use each mode*:

             • *any-same-blocker (default)*: Best for most users.  When
               you're on "Write tests" and press TAB, you'll see other
               tasks that also depend on "Set up project"—tasks you
               could work on in parallel after finishing the blocker.

             • *all-same-blockers*: Use when you want strict
               parallelism.  Only shows tasks that are truly equivalent
               alternatives—same prerequisites, same position in the
               workflow.

             • *dag-level*: Use when you think visually about your
               project.  Groups all tasks at the same "layer" or depth,
               regardless of their actual dependencies.

          *See also*: *note Graph View Command Reference:: for
          navigation keybindings.

   • Projects Configuration

        • ‘org-gtd-project-progress-cookie-position’

          *Type*: Symbol or nil

          *Default*: ‘'end’

          *Description*: Controls where progress cookies are displayed
          on project headings.

          Values:
          ‘nil’
               Disabled (no cookies shown)
          ‘'start’
               After TODO keyword, before title
          ‘'end’
               After heading text, before tags (default)

          Progress cookies show project completion as
          ‘[completed/total][percent%]’ format, for example
          ‘[3/7][42%]’.

          Unlike org-mode's built-in statistics cookies (‘[/]’ or ‘[%]’)
          which count direct children, org-gtd's progress cookies
          correctly count all tasks linked to the project via
          ‘ORG_GTD_PROJECT_IDS’, making them accurate for the DAG-based
          project structure.

          *Example*:
               ;; Show cookies at end of heading (default)
               (setq org-gtd-project-progress-cookie-position 'end)

               ;; Show cookies at start of heading
               (setq org-gtd-project-progress-cookie-position 'start)

               ;; Disable progress cookies
               (setq org-gtd-project-progress-cookie-position nil)

          *What it looks like*:
               ;; With 'end (default):
               * PROJ Buy a house [3/7][42%]                    :home:

               ;; With 'start:
               * PROJ [3/7][42%] Buy a house                    :home:

               ;; With nil:
               * PROJ Buy a house                               :home:

          *Automatic updates*: Cookies are automatically recalculated
          when:
             • Task TODO states change (via hook)
             • Project is created
             • ‘org-gtd-projects-fix-all-todo-keywords’ is run
             • ‘org-gtd-project-update-all-cookies’ is called manually

          *See also*: *note Project Progress Cookies: Project Progress
          Cookies See Your Progress at a Glance. for detailed usage,
          *note org-gtd-project-update-all-cookies:: for manual refresh.

   • Obsolete Variables (Do Not Use)

     These variables are obsolete as of version 4.0.  They are listed
     here for reference only.

        • ‘org-gtd-todo-keyword’ (obsolete)

          *Use instead*: ‘org-gtd-keyword-mapping’ with key ‘'todo’

        • ‘org-gtd-next-keyword’ (obsolete)

          *Use instead*: ‘org-gtd-keyword-mapping’ with key ‘'next’

        • ‘org-gtd-wait-keyword’ (obsolete)

          *Use instead*: ‘org-gtd-keyword-mapping’ with key ‘'wait’

        • ‘org-gtd-canceled-keyword’ (obsolete)

          *Use instead*: ‘org-gtd-keyword-mapping’ with key ‘'canceled’


File: org-gtd.info,  Node: Commands Reference,  Next: Properties Reference (Internal Implementation),  Prev: Configuration Variables Reference,  Up: Reference

1.5.2 Commands Reference
------------------------

This section lists all interactive commands available in org-gtd,
organized by workflow step.

   • Core GTD Workflow Commands

        • ‘org-gtd-command-center’

          *Binding*: Typically ‘C-c d’ (user-configurable)

          *When to use*: Anytime you want to access org-gtd
          functionality

          *What it does*:
             • Opens a transient menu with all major GTD operations
             • Provides quick access to common workflows
             • Serves as a discovery hub for new users

          *Menu structure*:
          Key   Command
          ------------------------------------
          e     Engage (daily view)
          @     Engage by context
          n     Show all next actions
          c     Capture to inbox
          p     Process inbox
          k     Clarify item at point
          a     Reflect: area of focus
          y     Reflect: someday/maybe
          d     Reflect: upcoming delegated
          r     Reflect: completed items
          R     Reflect: completed projects
          A     Archive completed items
          S     Stuck items sub-menu
          M     Missed items sub-menu

          *Sub-menus*:
             • ‘S’ opens stuck items menu: projects, calendar,
               delegated, habits, tickler, single actions
             • ‘M’ opens missed items menu: all missed, calendar,
               delegated, projects

        • ‘org-gtd-capture’

          *Binding*: Typically ‘C-c d c’ (user-configurable)

          *When to use*: Anytime something comes up that you need to
          capture

          *What it does*:
             • Opens org-capture for the inbox
             • Uses templates from ‘org-gtd-capture-templates’
             • Stores item in inbox.org for later processing

          *Arguments*: Optional ‘goto’ and ‘keys’ (same as
          ‘org-capture’)

          *Example usage*:
               M-x org-gtd-capture
               Type: "Call dentist to schedule checkup"
               C-c C-c to save

        • ‘org-gtd-process-inbox’

          *Binding*: Typically ‘C-c d p’

          *When to use*: When your inbox has items (daily or multiple
          times daily)

          *What it does*:
             • Starts processing loop through inbox items
             • Opens each item in a clarify buffer (WIP mode)
             • Continues until inbox is empty or you quit
             • If ‘org-gtd-additional-inbox-files’ is configured,
               continues through those files after main inbox

          *How to use*:
            1. Run command
            2. Edit each item to clarify it
            3. Press your organize binding (‘C-c c’) to organize it
            4. Repeat for next item

          *Related*: ‘org-gtd-clarify-item’ to clarify a single item
          without processing whole inbox

        • ‘org-gtd-organize’

          *Binding*: Typically ‘C-c c’ (only works in clarify buffers)

          *When to use*: After clarifying an item, to categorize it

          *What it does*:
             • Opens transient menu with organization options
             • Prompts for item-specific information (dates, names,
               etc.)
             • Runs organize hooks
             • Refiles item to appropriate location

          *Important*: This only works in clarify buffers
          (org-gtd-clarify-mode).  It won't work in regular org files.

          *Item types available*:
             • [P] Project
             • [A] Add to existing project
             • [C] Calendar
             • [D] Delegate
             • [S] Single action
             • [H] Habit
             • [I] Tickler
             • [y] Someday/Maybe
             • [K] Knowledge
             • [Q] Quick action
             • [T] Trash

        • ‘org-gtd-engage’

          *Binding*: Typically ‘C-c d e’

          *When to use*: Daily (or multiple times daily) to see what you
          can work on right now

          *What it does*:
             • Shows org-agenda view customized for GTD
             • Displays the following.
                  • Agenda for today (appointments, deadlines, scheduled
                    items)
                  • All NEXT actions (grouped by project)
             • Uses prefix width from ‘org-gtd-prefix-width’

          *Agenda commands available in this view*:
          ‘t’
               Change TODO state
          ‘RET’
               Visit item
          ‘r’
               Refile
          All other org-agenda commands
               Available as normal

        • ‘org-gtd-show-all-next’

          *Binding*: Typically ‘C-c d n’

          *When to use*: When you want to focus only on NEXT actions,
          without calendar/scheduled items

          *What it does*:
             • Shows all items with NEXT keyword
             • Simpler than engage view (no agenda section)
             • Useful for "get things done" focus mode

   • Reflect Commands

        • ‘org-gtd-reflect-stuck-projects’

          *Binding*: Typically ‘C-c d s’

          *When to use*: Weekly review, or when projects seem stalled

          *What it does*:
             • Finds projects that have active tasks but no NEXT actions
             • Indicates dependency problems or missing FIRST_TASKS

          *How to fix stuck projects*:
            1. Navigate to project heading
            2. Run
               ‘org-gtd-projects-fix-todo-keywords-for-project-at-point’
            3. If still stuck, check dependencies

        • ‘org-gtd-reflect-area-of-focus’

          *Arguments*: Optional AREA and START-DATE

          *When to use*: During weekly/monthly reviews to focus on
          specific life area

          *What it does*:
             • Generates agenda view for items tagged with a specific
               area of focus
             • Prompts for area if not provided
             • Shows all items (projects, actions, calendar) for that
               area

          *Example*:
               M-x org-gtd-reflect-area-of-focus
               Area: Work
               Shows: All Work-related items

        • ‘org-gtd-reflect-completed-items’

          *Arguments*: Optional DAYS-BACK (default 7)

          *When to use*: Weekly review to see what you accomplished

          *What it does*:
             • Shows items completed in the last N days
             • Good for weekly review reflection

          *Example*:
               M-x org-gtd-reflect-completed-items
               Shows: Items completed in last 7 days

               C-u 30 M-x org-gtd-reflect-completed-items
               Shows: Items completed in last 30 days

        • ‘org-gtd-reflect-completed-projects’

          *When to use*: Weekly/monthly review to see finished projects

          *What it does*:
             • Shows all projects where all tasks are DONE
             • Ready to archive

        • ‘org-gtd-reflect-missed-items’

          *When to use*: When you suspect items have fallen through the
          cracks

          *What it does*:
             • Finds items that should have been processed but weren't
             • Looks for various data inconsistencies

   • Stuck Item Review Commands

     Each of these commands finds items with problems in a specific
     category:

        • ‘org-gtd-reflect-stuck-calendar-items’

          Finds calendar items with invalid or missing timestamps.

        • ‘org-gtd-reflect-stuck-tickler-items’

          Finds tickler items with invalid or missing review dates.

        • ‘org-gtd-reflect-stuck-habit-items’

          Finds habit items with incorrect configuration.

        • ‘org-gtd-reflect-stuck-delegated-items’

          Finds delegated items with missing delegate or date
          information.

        • ‘org-gtd-reflect-stuck-single-action-items’

          Finds single actions that aren't marked as NEXT.

   • Reviewing Someday/Maybe Items

     Someday/maybe items are the graveyard of dreams—or the incubator of
     future greatness.  The difference?  Regular review.  This feature
     helps you stay connected to your possibilities without letting them
     become forgotten fossils.

     *What is it*: A wizard-style workflow that shows you each someday
     item one at a time, letting you quickly defer it (keep for later)
     or clarify it (reactivate and make it actionable).

     *Who needs it*: Anyone with someday/maybe items who wants to
     periodically review them during their GTD reflect process.

        • Your First Review in 60 Seconds

          Try this right now:

            1. Run ‘M-x org-gtd-reflect-someday-review’
            2. You'll see your first someday item in a read-only buffer
            3. Press ‘d’ to defer (keeps the item, logs that you
               reviewed it)
            4. Or press ‘c’ to clarify (reactivates the item)
            5. Press ‘q’ anytime to quit

          That's it.  You're reviewing your possibilities.

        • Understanding the Review Workflow

          When you see a someday item during review, you're asking
          yourself one question: "Is now the time to pursue this?"

               Someday item: "Learn to play piano"

               Is now the time?
                 YES → Press 'c' (clarify) → Item becomes active, you organize it fresh
                 NO  → Press 'd' (defer) → Item stays in someday, with timestamp logged

          *Why defer logs a timestamp*: The LOGBOOK entry creates a
          history.  During future reviews, you can see how long items
          have been sitting.  An item deferred 50 times over 3 years
          might be ready to trash—or finally pursue.

        • Tutorial: Weekly Someday Review

          Here's how to incorporate this into your weekly review:

          *Basic flow*:
               M-x org-gtd-reflect-someday-review

               For each item:
               - Read it
               - Decide: defer or clarify?
               - Press d or c
               - Repeat until "Review complete"

          *What happens when you clarify*:
            1. The item's previous state is restored (if it was a
               delegated action, it remembers the delegate)
            2. You go through the organize flow
            3. After organizing, review automatically continues with the
               next item

          *What happens when you defer*:
            1. A "Reviewed [timestamp]" entry is added to the item's
               LOGBOOK
            2. Review advances to the next item
            3. The item stays in someday/maybe

        • Organizing Your Someday Items (Optional)

          If your someday list grows large, you can group items into
          named lists:

               ;; Optional: Define someday lists for focused reviews
               (setq org-gtd-someday-lists '("Work Ideas" "Personal Projects" "Learning" "Travel"))

          With this configured:

            1. *When organizing items as someday*: You'll be prompted to
               choose a list
            2. *When reviewing*: You'll be prompted which list to review
               (or "Unassigned")
            3. *Programmatic access*: Call
               ‘(org-gtd-reflect-someday-review "Work Ideas")’ directly

          This is entirely optional.  Without configuration, all someday
          items are reviewed together.

        • Common Patterns

          *Monthly Deep Review*:
               ;; Review everything, no list filter
               M-x org-gtd-reflect-someday-review

               ;; Go through each item thoughtfully
               ;; This might take 15-30 minutes for 50 items

          *Focused Category Review*:
               ;; With org-gtd-someday-lists configured:
               M-x org-gtd-reflect-someday-review → "Learning"

               ;; Only see learning-related someday items

          *Finding Stale Items*: Look at items during review that have
          many LOGBOOK entries spanning years.  Ask yourself: "Am I ever
          actually going to do this?"  If not, trash it.  If yes, this
          might be the time to clarify it.

        • Command Reference

          Key   Command   What it does
          ----------------------------------------------------------
          ‘d’   Defer     Log "Reviewed" entry, advance to next
          ‘c’   Clarify   Reactivate item, triggers organize flow
          ‘q’   Quit      End review, show statistics

          *Statistics*: When you quit or finish, you'll see: "Review
          complete.  X items reviewed, Y clarified."

        • ‘org-gtd-reflect-someday-review’

          *Arguments*: Optional LIST (string)

          *When to use*: During weekly/monthly reviews, or anytime you
          want to reconnect with your possibilities

          *What it does*:
             • If ‘org-gtd-someday-lists’ is configured: prompts for
               which list to review
             • Shows each someday item in a read-only buffer
             • Single-keystroke actions: ‘d’ (defer), ‘c’ (clarify), ‘q’
               (quit)
             • Tracks statistics (items reviewed, items clarified)

          *Configuration*:
               ;; Optional: Group someday items into lists
               (setq org-gtd-someday-lists '("Work Ideas" "Personal" "Learning"))

          *Example*:
               ;; Interactive (will prompt for list if configured)
               M-x org-gtd-reflect-someday-review

               ;; Programmatic (skip list prompt)
               (org-gtd-reflect-someday-review "Work Ideas")

   • Reflect Commands (Missed Engagements)

        • What Are Missed Engagements?

          Life doesn't go as planned.  You miss appointments, delegated
          items slip through cracks, projects run late.  These aren't
          failures—they're normal.  What matters is catching them and
          deciding what to do next.

          The missed engagements review helps you find three types of
          items that need attention:
             • *Appointments you missed*: Calendar items with dates in
               the past
             • *Check-ins you forgot*: Delegated items where follow-up
               dates passed
             • *Projects running late*: Projects with overdue deadlines
               or start dates

          This is your safety net.  Run it daily or weekly to ensure
          nothing falls through the cracks.

        • Your First Review in 30 Seconds

          Try this right now:

            1. Run ‘M-x org-gtd-reflect-missed-engagements’
            2. Look at what appears in the agenda view
            3. Press ‘TAB’ on any item to see its details

          That's it.  You're now reviewing missed engagements.

          If you see items, ask yourself: "What should I do about this
          now?"  Then organize accordingly (reschedule, cancel, or act).

        • Understanding the Review Workflow

          Think of GTD like a promise system.  When you:
             • Schedule an appointment → you promise to be there at that
               time
             • Delegate a task → you promise to check in on the date you
               set
             • Set a project deadline → you promise to complete by that
               date

          When dates pass without action, you've broken a promise (to
          yourself or others).

          The review workflow helps you:
            1. *Find* broken promises (missed engagements)
            2. *Decide* what to do about them
            3. *Act* on your decision

          This isn't about guilt—it's about staying in control.

        • Tutorial: Daily Review Workflow

          Here's how to use this in your daily routine:

          *Morning Review* (2 minutes):
               M-x org-gtd-reflect-missed-engagements

               Look at each item:
               - Missed appointment? Reschedule or apologize
               - Forgot to check in on delegation? Do it now
               - Project running late? Decide: extend deadline or cancel

          *Focusing on One Type*:

          If you just want to see missed appointments:
               M-x org-gtd-reflect-missed-calendar

          Or just delegated items needing check-ins:
               M-x org-gtd-reflect-missed-delegated

          Or just late projects:
               M-x org-gtd-reflect-missed-projects

          Each command shows only that type, making it easier to focus.

        • Common Patterns

          *Pattern 1: Morning Triage* Start each day by reviewing missed
          engagements.  Handle or reschedule everything before starting
          new work.

          *Pattern 2: Weekly Cleanup* During weekly review, run the full
          missed engagements view.  This catches anything that slipped
          through daily reviews.

          *Pattern 3: Context-Specific Review* Use custom views to see
          missed items by area of focus (see configuration below).

        • Command Reference

          Command                                Shows                          Use When
          -------------------------------------------------------------------------------------------------------
          ‘org-gtd-reflect-missed-engagements’   All missed items               Daily/weekly review
          ‘org-gtd-reflect-missed-calendar’      Missed appointments only       Checking calendar
          ‘org-gtd-reflect-missed-delegated’     Delegations needing check-in   Following up on delegated work
          ‘org-gtd-reflect-missed-projects’      Late projects only             Project review
          ‘org-gtd-reflect-missed-with-custom’   All missed + custom views      Using custom filters

        • Backward Compatibility Note

          The old command names still work:
             • ‘org-gtd-oops’ → ‘org-gtd-reflect-missed-engagements’
             • ‘org-gtd-oops-calendar’ →
               ‘org-gtd-reflect-missed-calendar’
             • ‘org-gtd-oops-delegated’ →
               ‘org-gtd-reflect-missed-delegated’
             • ‘org-gtd-oops-projects’ →
               ‘org-gtd-reflect-missed-projects’
             • ‘org-gtd-oops-with-custom’ →
               ‘org-gtd-reflect-missed-with-custom’

          Update to the new names when convenient.  The old names will
          be removed in a future version.

   • Reflect Commands (Upcoming Delegated)

        • What Are Upcoming Delegated Check-ins?

          You delegate work and set check-in dates.  Some people finish
          early.  Others appreciate regular check-ins.  Waiting until
          check-in dates pass means lost opportunities.

          The upcoming delegated review shows all active delegated items
          with future check-in dates.  This helps you:
             • *Catch early completions*: Someone finished early, you
               can adjust the plan now
             • *Plan your follow-ups*: See what check-ins are coming
               this week or month
             • *Proactive management*: Reach out before problems develop

          This is your planning tool.  Use it weekly to prepare your
          delegation check-ins, or ad-hoc when people report early
          progress.

        • Your First Review in 30 Seconds

          Try this right now:

            1. Run ‘M-x org-gtd-reflect-upcoming-delegated’
            2. Look at the delegated items with future check-in dates
            3. Press ‘TAB’ on any item to see when the check-in is
               scheduled

          That's it.  You're now seeing upcoming delegation check-ins.

          If someone tells you they finished early, you'll find that
          item here and can update your plans accordingly.

        • Understanding Proactive Delegation Management

          Think about delegation timing:

          *Reactive management* (missed engagements):
             • Check-in date passes → you remember to follow up
             • Problem discovered after it's late
             • Always catching up

          *Proactive management* (upcoming review):
             • See check-ins coming this week → prepare questions
             • Someone finishes early → immediately unblock dependent
               work
             • Stay ahead of problems

          The upcoming delegated review shifts you from reactive to
          proactive.

        • Tutorial: Weekly Planning Workflow

          Here's how to use this in your weekly planning:

          *Sunday Planning* (5 minutes):
               M-x org-gtd-reflect-upcoming-delegated

               For each item:
               - Check-in this week? Prepare questions or schedule call
               - Might finish early? Be ready to adjust plans
               - Blocked on something? Follow up proactively

          *When Someone Reports Early Completion*:
               M-x org-gtd-reflect-upcoming-delegated

               Find their item in the list
               Press TAB to jump to the item
               Mark it DONE (it disappears from the upcoming view)
               Check if this unblocks other work in the project

          *Combined with Missed Review*:
               # Morning routine
               M-x org-gtd-reflect-missed-delegated    # Catch up on late check-ins
               M-x org-gtd-reflect-upcoming-delegated  # Plan upcoming check-ins

          The first shows what you missed.  The second shows what's
          coming.  Together they give complete delegation visibility.

        • Common Patterns

          *Pattern 1: Weekly Planning* Every Sunday or Monday, review
          upcoming delegated items for the week.  Know what check-ins
          are coming so you're prepared.

          *Pattern 2: Early Completion Response* When someone says "I
          finished that task you gave me," pull up this view to find it
          quickly and update your plans.

          *Pattern 3: Project Acceleration* Review a specific project's
          delegated items.  If anyone finished early, immediately
          reassign work to take advantage of the extra time.

          *Pattern 4: Delegation Optimization* Notice patterns: Who
          consistently finishes early?  Give them more work.  Who's
          always late?  More frequent check-ins.

        • Understanding What You See

          The view shows all active (not done) delegated items with
          future check-in dates:
             • Items with TODO, NEXT, or WAIT states
             • Items with check-ins far in the future (months away)
             • Items from all areas of focus

          Once you mark an item DONE or CNCL, it disappears from this
          view automatically—you've already processed it and taken
          action.

          If you see too many items and want to filter:
             • Focus on one project at a time (use project-specific
               review)
             • Look at specific timeframes (future enhancement—not yet
               implemented)
             • Use custom views with area-of-focus filters

        • Comparison: Missed vs Upcoming

          Review Type          Shows              Mindset                  Use When
          -----------------------------------------------------------------------------------
          Missed Delegated     Past check-ins     Reactive - catching up   Daily triage
          Upcoming Delegated   Future check-ins   Proactive - planning     Weekly planning

          Both are valuable.  Missed helps you catch problems.  Upcoming
          helps you prevent them.

        • Command Reference

          Command                                Shows                                            Use When
          --------------------------------------------------------------------------------------------------------------------------------------
          ‘org-gtd-reflect-upcoming-delegated’   All delegated items with future check-in dates   Weekly planning, early completion responses

   • Custom View Commands

        • ‘org-gtd-view-show’

          **What it is:** Create custom GTD agenda views using a
          declarative language instead of learning org-agenda skip
          function internals.

          **Why you'd use it:** The built-in views (engage,
          review-stuck-projects, etc.)  cover common needs, but you have
          unique workflows.  Maybe you only want to see work-related
          NEXT actions, or projects in a specific area, or items tagged
          "urgent".  This lets you create exactly the view you need.

          **Who needs it:** Users who want views tailored to their
          specific workflow beyond the built-in commands.

          **Your first custom view (5 minutes):**

          Let's create a view showing only your NEXT actions (no
          calendar, no agenda).

            1. Add this to your config file:
                    (defun my-next-actions ()
                      "Show all NEXT actions in a simple list."
                      (interactive)
                      (org-gtd-view-show
                       '((name . "All NEXT Actions")
                         (type . next-action))))

            2. Save and reload your config (‘M-x eval-buffer’ or restart
               Emacs)

            3. Run it:
                    M-x my-next-actions

          You'll see all your NEXT actions in one list.  That's
          it—you've created a custom view!

          **Understanding how views work:**

          Think of views like filtered searches.  You tell org-gtd what
          to show, and it finds matching items.

          The built-in ‘org-gtd-engage’ command?  It uses
          ‘org-gtd-view-show’ internally.
          ‘org-gtd-reflect-stuck-projects’?  Same thing.  You're now
          using the same tool the package uses to create its own views.

          View specs are simple: give it a ‘name’ and add filters.
          Filters are pairs like ‘(filter-type . value)’.  Multiple
          filters combine with AND logic—all must match.

               ;; Simple view spec
               '((name . "Delegated Items")
                 (type . delegated))

          The most common filter is ‘type’, which matches GTD item
          types: ‘project’, ‘next-action’, ‘calendar’, ‘delegated’,
          ‘tickler’, ‘someday’, ‘habit’, ‘stuck-project’,
          ‘completed-project’.

          **Tutorial: Common custom views**

          *Show only work-related NEXT actions:*

               (defun my-work-next-actions ()
                 "Show NEXT actions for work projects only."
                 (interactive)
                 (org-gtd-view-show
                  '((name . "Work NEXT Actions")
                    (type . next-action)
                    (area-of-focus . "Work"))))

          Two filters: must be a next-action AND must be in Work area.

          *Show projects that are stuck:*

               (defun my-stuck-projects ()
                 "Show projects with no NEXT actions."
                 (interactive)
                 (org-gtd-view-show
                  '((name . "Stuck Projects")
                    (type . stuck-project))))

          One filter: type must be stuck-project (built-in type that
          checks for stuck state).

          *Show delegated items due today:*

               (defun my-delegated-today ()
                 "Show delegated items with check-ins due today."
                 (interactive)
                 (org-gtd-view-show
                  '((name . "Delegated Check-ins Today")
                    (type . delegated)
                    (when . today))))

          The ‘when’ filter uses semantic time: ‘today’, ‘past’, or
          ‘future’.  It automatically knows that for delegated items,
          "when" means the ‘ORG_GTD_TIMESTAMP’ property.

          *Show multiple related views together:*

               (defun my-morning-review ()
                 "Show morning planning views: NEXT actions and calendar."
                 (interactive)
                 (org-gtd-view-show
                  '(((name . "Today's NEXT Actions")
                     (type . next-action))
                    ((name . "Delegated Items to Follow Up")
                     (type . delegated)
                     (when . today)))))

          This shows TWO views in one agenda: NEXT actions first, then
          delegated items due today.

          **Common patterns:**

          *Filter by type (most common):*
               (type . project)          ; All projects
               (type . next-action)      ; Single actions (with NEXT keyword)
               (type . delegated)        ; Delegated items (with WAIT keyword)
               (type . calendar)         ; Calendar items
               (type . tickler)          ; Tickler items (time-based reminders)
               (type . someday)          ; Someday/maybe items
               (type . habit)            ; Habits
               (type . stuck-project)    ; Projects needing attention
               (type . completed-project) ; Projects ready to archive

          *Filter by semantic time (‘when’):*
               (when . today)            ; Items due today
               (when . past)             ; Missed items
               (when . future)           ; Upcoming items

          The ‘when’ filter automatically uses the right timestamp
          property for each type:
             • For ‘delegated’ and ‘calendar’: checks
               ‘ORG_GTD_TIMESTAMP’
             • For ‘tickler’: checks the tickler review date

          *Filter by area of focus:*
               (area-of-focus . "Work")

          *Combine multiple filters (AND logic):*
               '((name . "Overdue Work Projects")
                 (type . project)
                 (area-of-focus . "Work")
                 (deadline . past))
               ;; Shows: Projects AND Work area AND overdue

          **When to create custom views:**

          Create a custom view when you find yourself:
             • Repeatedly filtering the engage view manually
             • Wanting to see specific combinations org-gtd doesn't
               provide
             • Needing views for specific contexts (home office,
               traveling, morning routine)
             • Organizing weekly reviews around specific categories

          Don't create views for one-time queries—just use the built-in
          views and navigate.  Create views for repeated patterns in
          your workflow.

          **Binding to keys:**

          Once you've created a view you use often, bind it to a key:

               ;; Vanilla Emacs
               (global-set-key (kbd "C-c d w") 'my-work-next-actions)

               ;; Doom Emacs (in config.el)
               (map! :leader
                     (:prefix "d"
                      :desc "Work NEXT actions" "w" #'my-work-next-actions))

               ;; Spacemacs (in user-config)
               (spacemacs/set-leader-keys "od w" 'my-work-next-actions)

          **Complete filter reference:**

          For the full list of available filters and their syntax, see
          *note View DSL Reference: View DSL Filter Reference.

          Common filters include:
          ‘type’
               project, next-action, delegated, calendar, tickler,
               someday, habit, stuck-project, completed-project,
               stuck-delegated, stuck-calendar, stuck-tickler,
               stuck-habit
          ‘when’
               Semantic time filter (today, past, future) -
               automatically uses correct property per type
          ‘area-of-focus’
               Specific area/category
          ‘deadline’, ‘scheduled’
               Org timestamp filters (past, future, today)
          ‘tags’
               Match specific tags

          **Command reference:**

          *Function signature:*
               (org-gtd-view-show VIEW-SPEC-OR-SPECS &optional KEYS)

          *Arguments:*
          ‘VIEW-SPEC-OR-SPECS’
               Either a single view specification (alist) or list of
               view specifications
          ‘KEYS’
               Optional string used as the agenda dispatch key (defaults
               to "g").  When ‘org-agenda-sticky’ is non-nil, different
               KEYS values allow multiple independent agenda views to be
               displayed simultaneously

          *View specification structure:*
               ;; Simple view - filters are top-level
               '((name . "View Name")
                 (type . delegated)
                 (when . past))

          *Multiple views:*
               '(((name . "View 1")
                  (type . next-action))
                 ((name . "View 2")
                  (type . stuck-project)))

          *Returns:* Opens org-agenda buffer with the specified view

          *Example:*
               ;; Single view
               (org-gtd-view-show
                '((name . "Active Projects")
                  (type . project)))

               ;; Multiple views
               (org-gtd-view-show
                '(((name . "NEXT Actions")
                   (type . next-action))
                  ((name . "Stuck Projects")
                   (type . stuck-project))))

          **Using Multiple Concurrent Views:**

          By default, calling ‘org-gtd-view-show’ multiple times
          replaces the previous agenda buffer.  To display multiple
          views simultaneously:

            1. Enable sticky agenda buffers:
                    (setq org-agenda-sticky t)

            2. Pass different KEYS to each call:
                    (defun my-dashboard ()
                      "Show my GTD dashboard with multiple views."
                      (interactive)
                      (delete-other-windows)
                      (org-gtd-view-show '((name . "Next Actions") (type . next-action)) "a")
                      (split-window-right)
                      (other-window 1)
                      (org-gtd-view-show '((name . "Calendar") (type . calendar)) "c"))

          Each view will appear in its own buffer: ‘*Org Agenda(a)*’,
          ‘*Org Agenda(c)*’, etc.

   • Clarification Commands

        • ‘org-gtd-clarify-item’

          *Arguments*: Optional MARKER and WINDOW-CONFIG

          *When to use*: To clarify a single org heading without
          processing the entire inbox

          *What it does*:
             • Opens item in clarify buffer (WIP mode)
             • You can edit and organize it
             • Returns to previous location when done

          *Example*: Clarifying an item in your tasks file that needs
          re-organization.

        • ‘org-gtd-clarify-agenda-item’

          *When to use*: When viewing agenda and want to re-clarify an
          item

          *What it does*:
             • Opens agenda item in clarify buffer
             • Same as ‘org-gtd-clarify-item’ but works from agenda view

        • ‘org-gtd-clarify-toggle-horizons-window’

          *When to use*: During clarification, to show/hide your
          horizons file

          *What it does*:
             • Toggles display of horizons file in side window
             • Position determined by ‘org-gtd-clarify-show-horizons’
               (or right side if variable is nil)

        • ‘org-gtd-clarify-toggle-organize-help’

          *When to use*: During clarification, when you're unsure which
          GTD category to choose

          *What it does*:
             • Toggles display of organize types help buffer in side
               window
             • Shows all GTD item types (Quick Action, Single Action,
               Project, etc.)  with keyboard shortcuts and brief
               descriptions
             • Position determined by
               ‘org-gtd-clarify-show-organize-help’ (or right side if
               variable is nil)

        • ‘org-gtd-clarify-project-insert-template’

          *When to use*: During project clarification, to insert a
          predefined template

          *What it does*:
             • Prompts for template from
               ‘org-gtd-clarify-project-templates’
             • Inserts template tasks into current project

        • ‘org-gtd-clarify-duplicate’

          *Binding*: ‘d’ (in clarify buffers)

          *When to use*: When an item you're clarifying represents
          multiple outcomes

          *What it does*:
             • Prompts for a title (current title as default)
             • Creates a duplicate with that title
             • Adds duplicate to a queue
             • Shows queue window if not already visible
             • After organizing current item, the duplicate opens for
               clarification

          *Example*: You captured "Prepare for Monday meeting" but
          realize it's three things: book room, prepare slides, send
          agenda.  Press ‘d’, type "Book meeting room", press RET.
          Repeat for each outcome.

          *See also*: *note Duplicating items during clarification::

        • ‘org-gtd-clarify-duplicate-exact’

          *Binding*: ‘D’ (in clarify buffers)

          *When to use*: When you want an identical copy without
          changing the title

          *What it does*:
             • Creates exact duplicate (no prompt)
             • Adds to queue immediately

          *Example*: Same task needs to be delegated to multiple people.
          Duplicate exactly, then organize each copy as delegated to a
          different person.

        • ‘org-gtd-clarify-stop’

          *Binding*: ‘C-c C-k’ (in clarify buffers)

          *When to use*: To abort clarification and discard changes

          *What it does*:
             • If duplicates are pending: prompts to discard, save to
               inbox, or cancel
             • Kills the WIP buffer
             • Restores previous window configuration

        • Updating Items Without Refiling

          **What this is:** A way to reconfigure existing GTD items
          (change their category, properties, or details) without moving
          them to a different location in your files.

          **Who needs it:** Anyone who wants to change how an item is
          organized while keeping it where it is - perfect for items
          already in projects, or when you like your current file
          organization.

          **Your first use (30 seconds):**

          You're looking at your agenda and see a single action that
          should actually be delegated.  But it's already in a specific
          project file and you want it to stay there:

            1. In agenda view, put point on the item
            2. Type: ‘C-u M-x org-gtd-clarify-agenda-item’
            3. Make your changes in the clarify buffer
            4. Type: ‘M-x org-gtd-organize’
            5. Type: ‘-n’ to toggle "Update in place (no refile)"
            6. Choose: ‘d’ for Delegate
            7. Fill in delegation details
            8. Done - item is updated but stays in its current location

          **How it works:**

          Normally when you organize an item, org-gtd moves (refiles) it
          to the appropriate GTD type location.  But sometimes you want
          to change the configuration without moving the item.

          There are two ways to trigger this:

          *Via prefix argument:*
             • ‘C-u M-x org-gtd-clarify-item’ - Clarify item at point
               without refiling
             • ‘C-u M-x org-gtd-clarify-agenda-item’ - Clarify agenda
               item without refiling

          *Via transient toggle:*
             • During organization, press ‘-n’ in the ‘org-gtd-organize’
               menu to toggle "Update in place (no refile)"
             • The toggle is only available when NOT processing the
               inbox (inbox items must be refiled)

          When the skip-refile flag is set, organizing the item will:
             • Apply all the same configuration (properties, tags,
               hooks)
             • Update the item in its current location
             • NOT move it to a different file or heading

          **Common scenarios:**

          *Reconfiguring project tasks:*
             • Task is already in the right project file
             • You want to change it from single action to delegated
             • Use skip-refile to update without moving

          *Adjusting agenda items:*
             • Item appears in your daily agenda
             • You realize it needs different properties (change
               deadline, add delegation, etc.)
             • Use skip-refile to update configuration in place

          *Organizing items in custom locations:*
             • You've organized items in a specific way outside
               ‘org-gtd-directory’
             • You want to apply GTD types but preserve your file
               structure
             • Use skip-refile to maintain your organization

          **What stays the same vs what changes:**

          *Changes applied:*
             • GTD type (ORG_GTD property)
             • TODO keyword state
             • Properties (delegation info, dates, etc.)
             • Tags
             • All organize hooks

          *Preserved:*
             • File location
             • Position within file
             • Parent heading (for tasks in projects)
             • Sibling relationships

          **Technical details:**

          When you set the skip-refile flag (via ‘C-u’ prefix or ‘-n’
          toggle):
             • The flag is stored in the clarify buffer as
               ‘org-gtd-clarify--skip-refile’
             • Category finalize functions check this flag
             • If set, they call ‘org-gtd-organize--update-in-place’
               instead of refiling
             • The original heading is replaced with the configured
               content from the WIP buffer
             • Archive categories (quick-action, knowledge, trash)
               always archive regardless of this flag

          **Migration note:**

          In previous versions, there was a special command
          ‘org-gtd-delegate-item-at-point’ for delegating items without
          moving them.  This command has been removed in favor of the
          more general skip-refile mechanism:

          *OLD way (no longer available):*
               M-x org-gtd-delegate-item-at-point

          *NEW way (version 4.0+):*
               ;; From agenda or file:
               C-u M-x org-gtd-clarify-item
               ;; or
               C-u M-x org-gtd-clarify-agenda-item
               ;; Then organize and press -n toggle
               M-x org-gtd-organize
               ;; Press -n to enable skip-refile
               ;; Choose delegation

          The new approach is more flexible - it works for ANY GTD type,
          not just delegation.

   • Archive Commands

        • ‘org-gtd-archive-completed-items’

          *When to use*: Weekly or monthly cleanup

          *What it does*:
             • Finds all DONE/CNCL items in GTD files
             • Archives them to location specified by
               ‘org-gtd-archive-location’
             • Keeps your active files clean

          *Example*:
               M-x org-gtd-archive-completed-items
               Archives: All completed items
               Result: Clean active files, archived items in archive file(s)

   • Agenda-Specific Commands

     These commands only work when point is on an agenda item:

        • ‘org-gtd-delegate-agenda-item’

          *When to use*: In agenda view, to delegate an existing action
          to someone else

          *What it does*:
             • Prompts for person to delegate to
             • Prompts for follow-up date
             • Updates item properties
             • Refiles to delegated items location

        • ‘org-gtd-project-cancel-from-agenda’

          *When to use*: In agenda view, when you want to cancel an
          entire project

          *What it does*:
             • Finds the project containing the agenda item
             • Prompts for confirmation before proceeding
             • Marks all remaining incomplete tasks as CNCL (preserves
               DONE tasks)
             • Sets the project heading to CNCL

   • Timestamp Commands (DWIM)

     These commands work from any context: org buffer or agenda view.
     They automatically detect where you are.

        • ‘org-gtd-set-timestamp’

          *When to use*: To reschedule a Calendar, Delegated, or Tickler
          item

          *What it does*:
             • Prompts for a new date
             • Sets the ‘ORG_GTD_TIMESTAMP’ property
             • Works from org-mode headings or agenda items

          *Example*: You have a Calendar item for a meeting next week,
          but the meeting got moved.  Navigate to the item (either in
          org-mode or via the agenda), call ‘M-x org-gtd-set-timestamp’,
          pick the new date.

          *Note*: In the agenda transient (‘org-gtd-agenda-transient’),
          this is the ‘s’ "Set date" action.

   • Project Task Commands (DWIM)

     These commands work from any context: org buffer, agenda view, or
     graph view.  They automatically detect where you are and do the
     right thing.

        • ‘org-gtd-project-add-successor’

          *When to use*: To add a new task that depends on the current
          task

          *What it does*:
             • In graph view: opens multi-select transient for choosing
               predecessors
             • In org/agenda: task at point becomes the predecessor,
               prompts for new task title
             • Creates dependency relationships automatically
             • Updates TODO states

        • ‘org-gtd-project-add-blocker’

          *When to use*: To add a new task that must complete before the
          current task

          *What it does*:
             • In graph view: opens multi-select transient for choosing
               blocked tasks
             • In org/agenda: task at point becomes the blocked task,
               prompts for new blocker title
             • Creates dependency relationships automatically
             • Updates TODO states

        • ‘org-gtd-project-add-root-task’

          *When to use*: To add a new task with no dependencies (can
          start immediately)

          *What it does*:
             • In graph view: opens transient for task creation
             • In org/agenda: prompts for task title directly
             • Adds task as a root task (no blockers)
             • Updates TODO states

        • ‘org-gtd-project-remove-task’

          *When to use*: To remove a task from its project while keeping
          the task

          *What it does*:
             • Removes task from project structure
             • Rewires dependencies: predecessors are connected to
               successors
             • Keeps the task itself (does not delete it)
             • Updates TODO states

        • ‘org-gtd-project-trash-task’

          *When to use*: To completely remove a task from all projects

          *What it does*:
             • Removes task from ALL projects it belongs to
             • Cleans up ALL dependency relationships
             • Marks the task as canceled (CNCL)
             • Updates TODO states in affected projects

        • ‘org-gtd-project-change-state’

          *When to use*: To change the TODO state of a task

          *What it does*:
             • Prompts for new TODO state
             • Updates the task state
             • Works from any context (org buffer, agenda, graph view)

   • Project Management Commands

        • ‘org-gtd-projects-fix-todo-keywords-for-project-at-point’

          *When to use*: When project TODO states seem incorrect after
          dependency changes

          *What it does*:
             • Recalculates which tasks should be NEXT based on
               dependency graph
             • Updates all task keywords in the project
             • Fixes stuck projects

          *Required*: Point must be on project heading

          *Note*: This is automatically called after graph UI operations
          and text-based task management commands.  You typically only
          need this for troubleshooting edge cases.

        • ‘org-gtd-projects-fix-all-todo-keywords’

          **What it is:** Recalculates and fixes TODO/NEXT states for
          ALL projects in your GTD system at once.

          **Why you'd use it:** After making changes in external tools
          (mobile apps, web interfaces, other editors) that don't know
          about org-gtd's dependency logic, your task states might be
          inconsistent.  This command makes everything sane again.

          **Who needs it:** Anyone who edits their GTD files outside of
          org-gtd (mobile apps, sync conflicts, manual edits).

          **Your first use (30 seconds):**

            1. Edit tasks on your phone/tablet/other tool
            2. Sync back to Emacs
            3. Run: ‘M-x org-gtd-projects-fix-all-todo-keywords’
            4. Done - all task states are now correct

          That's it.  No need to manually check each project.

          **Common scenarios:**

             • Completed tasks on mobile → states might be wrong → run
               this
             • Changed task descriptions/notes externally → run this to
               be safe
             • Sync conflict resolution → run this after fixing
               conflicts
             • Bulk manual edits outside org-gtd → run this
             • After migration or data import → run this

          **When to use this vs the single-project version:**

          Use ‘org-gtd-projects-fix-all-todo-keywords’ when:
             • You've worked in external tools (mobile, web, other
               editors)
             • You've edited multiple projects
             • You don't know which projects are affected
             • You want to fix everything at once (safest option)

          Use ‘org-gtd-projects-fix-todo-keywords-for-project-at-point’
          when:
             • You know which specific project has issues
             • You've just edited one project in Emacs
             • You want to fix just one project quickly

          **What it does (technical):**

            1. Scans all projects in agenda files
            2. Resets active task states (TODO/NEXT → TODO)
            3. Calculates which tasks are ready based on dependencies
            4. Marks ready tasks as NEXT
            5. Preserves user-set states (WAIT, DONE, CNCL)
            6. Handles multi-project tasks correctly (AND semantics)

          **Multi-project tasks:**

          Some tasks can belong to multiple projects.  This command
          handles them safely:
             • Shared task becomes NEXT only if ready in ALL its
               projects
             • If ready in just some projects, stays TODO
             • WAIT states are never auto-changed

          **When NOT to use:**

             • If you only work in Emacs with org-gtd commands
               (automatic state management works)
             • If your projects look correct already
             • Before making external changes (use after, not before)

        • ‘org-gtd-project-update-all-cookies’

          **What it is:** Refreshes progress cookies on ALL project
          headings at once.

          **Why you'd use it:** Progress cookies show ‘[3/7][42%]’ on
          project headings.  While these update automatically when you
          change task states, sometimes you want to refresh
          everything—for example, after bulk changes or data migration.

          **Your first use (30 seconds):**

            1. Run: ‘M-x org-gtd-project-update-all-cookies’
            2. Done - all project headings now show accurate progress

          **What it does:**

             • Scans all projects in agenda files
             • Counts completed vs total tasks for each project
             • Updates the ‘[completed/total][percent%]’ display on each
               project heading

          **When to use:**

             • After bulk task changes outside of org-gtd
             • After data migration or import
             • During weekly review for visual refresh
             • If progress cookies look outdated

          **Configuration:**

          Progress cookies are controlled by
          ‘org-gtd-project-progress-cookie-position’:
             • ‘'end’ (default) - cookies appear at end of heading
               before tags
             • ‘'start’ - cookies appear after TODO keyword
             • ‘nil’ - cookies disabled entirely

          *See also*: *note Project Progress Cookies: Project Progress
          Cookies See Your Progress at a Glance. for detailed usage
          guide.

        • ‘org-gtd-tickler’

          **What it is:** Smart command to pause items with a specific
          review date (time-based reminder).

          **Why you'd use it:** You have a project or action that's a
          good idea, but not ready NOW.  You want to set it aside with a
          specific date to review it later, without losing your planning
          work.

          **Who needs it:** Anyone managing items that need to be
          deferred until a specific time or date.

          **Your first use (30 seconds):**

            1. Navigate to a project or action
            2. Run: ‘M-x org-gtd-tickler’
            3. Enter review date: ‘2025-12-01’
            4. Done - it disappears from your engage view until that
               date

          **What it does:**

          Detects what you're on:
             • Project heading → ticklers entire project with all tasks
             • Project task → ticklers the project it belongs to
             • Single action → ticklers just that action

          For projects:
             • Preserves all task states and dependencies
             • Hides everything from engage/NEXT views
             • Adds review date to your agenda
             • Multi-project tasks: only incubated if this is the task's
               last active project

          **When to use:**

             • Projects you want to start on a specific future date
             • Seasonal projects (start each year at a certain time)
             • Projects blocked by external factors with an expected
               resolution date
             • Items you want to reconsider after a specific event or
               milestone

          **Note:** For items with NO specific timeframe ("maybe
          someday"), use ‘org-gtd-someday’ instead.

        • ‘org-gtd-someday’

          **What it is:** Smart command to put items on someday/maybe
          (no specific timeframe).

          **Why you'd use it:** You have a project or action that's a
          possibility, but you're not committing to it.  No review
          date—you'll reconsider during your periodic reviews.

          **Who needs it:** Anyone managing items that need to be
          deferred indefinitely without a specific review date.

          **Your first use (30 seconds):**

            1. Navigate to a project or action
            2. Run: ‘M-x org-gtd-someday’
            3. If ‘org-gtd-someday-lists’ is configured, select a list
            4. Done - it disappears from your engage view

          **What it does:**

          Detects what you're on:
             • Project heading → puts entire project on someday/maybe
               with all tasks
             • Project task → puts the project it belongs to on
               someday/maybe
             • Single action → puts just that action on someday/maybe

          For projects:
             • Preserves all task states and dependencies
             • Hides everything from engage/NEXT views
             • Multi-project tasks: only incubated if this is the task's
               last active project

          **When to use:**

             • Ideas you want to keep but have no commitment to
             • Projects you're not ready for and don't have a review
               date in mind
             • Items that might become relevant but have no timeline

          **Note:** For items with a SPECIFIC review date, use
          ‘org-gtd-tickler’ instead.

        • ‘org-gtd-reactivate’

          **What it is:** Bring back tickler or someday items to their
          original active state.

          **Why you'd use it:** You're ready to work on something you
          previously set aside—either a tickler item whose review date
          arrived, or a someday item you've decided to act on.

          **Your first use (30 seconds):**

            1. Navigate to a tickler or someday item
            2. Run: ‘M-x org-gtd-reactivate’
            3. For non-project items: confirm or update each saved
               property when prompted
            4. For projects: graph view opens for review

          **What it does:**

          *For all items:*
             • Restores original ‘ORG_GTD’ value from ‘PREVIOUS_ORG_GTD’
             • Restores TODO keyword from ‘PREVIOUS_TODO’
             • Removes ‘ORG_GTD_TIMESTAMP’ (tickler review date)

          *For non-project items (delegated, calendar, single actions):*
             • Prompts you to confirm or update each type-specific
               property
             • Example: "Delegated to [Jane Smith]: " lets you keep Jane
               or enter someone new
             • Example: "Scheduled _[2025-03-15 Sat]_: " lets you update
               the date

          *For projects:*
             • Iterates over all project tasks restoring each one
             • Recalculates NEXT tasks based on current dependencies
             • Opens project graph view for review

          **When to use:**

             • When a tickler item appears in your agenda on its review
               date
             • During someday/maybe review when you decide to activate
               an item
             • When you're ready to reactivate something earlier than
               scheduled
             • During weekly review when scanning tickler or someday
               items

          **Note:** If an item has no saved state (‘PREVIOUS_ORG_GTD’ is
          empty), reactivation will start the organize workflow so you
          can categorize it fresh.

   • Task Dependency Commands

     These text-based commands manage task relationships without using
     the graph view.  Most users will find the graph view more intuitive
     (press ‘M-x org-gtd-show-project-graph’), but these commands are
     useful for:

        • Working in the org file directly
        • Scripting/automation
        • Preference for text-based workflows

     *Graph UI equivalents*:
        • Adding tasks with dependencies: ‘r’ (root), ‘s’ (successor),
          ‘b’ (blocker)
        • Modifying relationships: ‘B’ (modify blockers), ‘S’ (modify
          dependents)
        • Viewing relationships: ‘i’ (show relationships)

     See *note Graph View Command Reference:: for the visual approach.

        • ‘org-gtd-task-add-blockers’

          *When to use*: To specify that the current task depends on
          other task(s) completing first

          *What it does*:
             • Prompts to select tasks that block the current task
             • Creates bidirectional relationships.
                  • Adds selected task IDs to current task's
                    ORG_GTD_DEPENDS_ON
                  • Adds current task ID to selected tasks'
                    ORG_GTD_BLOCKS
             • Can select multiple blockers

          *Example*:
               On task: "Get diagnosis"
               M-x org-gtd-task-add-blockers
               Select: "Make MRI appointment" and "Make orthopedist appointment"
               Result: Both appointments must complete before diagnosis can start

        • ‘org-gtd-task-remove-blockers’

          *When to use*: To remove blocking relationships from current
          task

          *What it does*:
             • Shows current blockers
             • Prompts to select which to remove
             • Removes bidirectional relationships

        • ‘org-gtd-task-add-dependent’

          *When to use*: To specify that another task depends on the
          current task completing

          *What it does*:
             • Prompts to select a task that depends on current task
             • Creates bidirectional relationship.
                  • Adds selected task ID to current task's
                    ORG_GTD_BLOCKS
                  • Adds current task ID to selected task's
                    ORG_GTD_DEPENDS_ON

          *Example*:
               On task: "Get project approval"
               M-x org-gtd-task-add-dependent
               Select: "Start implementation"
               Result: Implementation can't start until approval is done

        • ‘org-gtd-task-add-dependents’

          *When to use*: To specify multiple tasks that depend on the
          current task

          *What it does*:
             • Same as ‘org-gtd-task-add-dependent’ but allows multiple
               selections

        • ‘org-gtd-task-clear-relationships’

          *When to use*: To remove ALL dependency relationships from
          current task

          *What it does*:
             • Removes all ORG_GTD_BLOCKS and ORG_GTD_DEPENDS_ON
               properties
             • Updates related tasks to remove references to this task
             • Use with caution!

        • ‘org-gtd-task-show-relationships’

          *When to use*: To see what tasks are related to the current
          task

          *What it does*:
             • Displays in minibuffer.
                  • Tasks this task depends on (blockers)
                  • Tasks that depend on this task (dependents)
             • Useful for understanding dependency graph

        • ‘org-gtd-validate-project-dependencies’

          *When to use*: To check for dependency problems in a project

          *What it does*:
             • Detects broken dependency references (task IDs that don't
               exist)
             • Finds orphaned tasks (not reachable from FIRST_TASKS)
             • Identifies circular dependencies
             • Provides guidance on fixes

          *Required*: Point must be on project heading

        • ‘org-gtd-remove-task-from-project’

          *When to use*: To remove a task from a project structure

          *What it does*:
             • Removes the project ID from task's ORG_GTD_PROJECT_IDS
               property
             • Doesn't delete the task, just removes project association
             • Useful when reorganizing project structures

   • Area of Focus Commands

        • ‘org-gtd-area-of-focus-set-on-item-at-point’

          *When to use*: To add area of focus to an existing item (not
          during organize)

          *What it does*:
             • Prompts for area from ‘org-gtd-areas-of-focus’
             • Sets CATEGORY property
             • Use this on any org heading

          *Note*: Trusts you to use it correctly (no validation)

        • ‘org-gtd-area-of-focus-set-on-agenda-item’

          *When to use*: In agenda view, to set area of focus on an item

          *What it does*:
             • Same as ‘org-gtd-area-of-focus-set-on-item-at-point’ but
               from agenda
             • Smarter: detects if you're on a project task and sets
               area on the project instead

   • Programmatic Creation Commands

     These commands create GTD items programmatically (useful for
     automation and Emacs Lisp code):

        • ‘org-gtd-habit-create’

          *Arguments*: STRING and additional parameters

          *Use case*: Creating habits from Emacs Lisp

          *Example*:
               (org-gtd-habit-create "Exercise" "daily" (org-read-date nil nil "+0d"))

        • ‘org-gtd-calendar-create’

          *Arguments*: STRING and DATE-TIME

          *Use case*: Creating calendar items from Emacs Lisp

          *Example*:
               (org-gtd-calendar-create "Team meeting" (org-read-date nil nil "+7d 9:00"))

        • ‘org-gtd-delegate-create’

          *Arguments*: STRING, DELEGATED-TO, and REMINDER-DATE

          *Use case*: Auto-delegating from email, code review systems,
          etc.

          *Example*:
               (defun org-gtd-email-reminder ()
                 (let ((topic (message-fetch-field "subject"))
                       (delegated-to (message-fetch-field "to"))
                       (reminder-date (org-read-date nil nil "+3d")))
                   (org-gtd-delegate-create (format "Reminder: %s" topic)
                                            delegated-to
                                            reminder-date)))

               (add-hook 'message-send-hook 'org-gtd-email-reminder)

        • ‘org-gtd-tickler-create’

          *Arguments*: STRING and REVIEW-DATE

          *Use case*: Programmatically adding tickler items (time-based
          reminders)

          *Example*:
               (org-gtd-tickler-create "Review Q2 goals" (org-read-date nil nil "+3m"))

        • ‘org-gtd-someday-create’

          *Arguments*: STRING

          *Use case*: Programmatically adding someday/maybe items (no
          specific timeframe)

          *Example*:
               (org-gtd-someday-create "Learn Rust")

        • ‘org-gtd-single-action-create’

          *Arguments*: STRING

          *Use case*: Programmatically adding actions

          *Example*:
               (org-gtd-single-action-create "Follow up on proposal")

   • Utility Commands

        • ‘org-gtd-setup-keywords-wizard’

          *When to use*: Initial setup or when changing keyword
          configuration

          *What it does*:
             • Interactive wizard to configure GTD keyword mapping
             • Guides you through setting up ‘org-gtd-keyword-mapping’
             • Validates configuration

        • ‘org-gtd-inbox-path’

          *Not interactive, but useful in Emacs Lisp*

          *Returns*: Full path to inbox.org file

          *Use case*: When writing custom capture templates or
          automation

          *Example*:
               (defun my-custom-capture ()
                 (let ((inbox (org-gtd-inbox-path)))
                   ;; do something with inbox file
                   ))

   • Migration and Upgrade Commands

        • ‘org-gtd-upgrade-v3-to-v4’

          *When to use*: REQUIRED when upgrading from version 3.x to 4.0

          *What it does*:
            1. Adds ORG_GTD properties to identify items
            2. Converts TRIGGER-based projects to dependency-based
               system
            3. Updates task states based on new dependency graph

          *Important*:
             • Make a backup first!
             • Required for existing projects to work in v4
             • Safe to run multiple times
             • See *note Upgrading section: Upgrading. for complete
               details

   • Mode-Line Integration

        • ‘org-gtd-mode’

          *Type*: Global minor mode

          *What it does*:
             • Displays inbox count in mode-line (e.g., ‘GTD[5]’)
             • Counts items across main inbox and additional inbox files
             • Refreshes periodically to catch external file changes
             • Enables org-edna for task dependencies
             • Detects when a project heading is manually set to CNCL
               (e.g., via ‘C-c C-t’) and prompts for confirmation before
               cascading the cancellation to incomplete child tasks

          *How to enable*:
               (org-gtd-mode 1)

          *Related*: ‘org-gtd-mode-update-interval’ to control refresh
          frequency

        • ‘org-gtd-inbox-count’

          *Returns*: Integer count of items across all inbox files

          *Use case*: Programmatic access to inbox count for custom
          displays or automation.

               (message "You have %d items to process" (org-gtd-inbox-count))

   • Obsolete Commands

        • ‘org-gtd-delegate-item-at-point’ (removed in 4.0)

          *Use instead*: Skip-refile feature with clarify commands

          This command was removed because it only solved one specific
          case (delegating without moving).  The new skip-refile feature
          is more general and works for any GTD type.

          *Migration*:
               ;; OLD (no longer available):
               M-x org-gtd-delegate-item-at-point

               ;; NEW (works from agenda or file):
               C-u M-x org-gtd-clarify-agenda-item
               ;; or
               C-u M-x org-gtd-clarify-item
               ;; Then in organize menu: press -n to toggle skip-refile, choose delegation

          See *note Clarification Options: Options and commands related
          to clarification. for full documentation on the skip-refile
          feature.


File: org-gtd.info,  Node: Properties Reference (Internal Implementation),  Next: Troubleshooting Projects,  Prev: Commands Reference,  Up: Reference

1.5.3 Properties Reference (Internal Implementation)
----------------------------------------------------

*For most users*: You don't need to read this section!  Use the graph
view or text-based task management commands instead.

   *This section is for*:
   • Understanding org-gtd's internal data model
   • Writing elisp automation/integration code
   • Debugging edge cases
   • Migrating data from other systems

   org-gtd uses org-mode properties to track state and relationships.
These properties are managed automatically by org-gtd commands - *you
should not edit them manually during normal use.*

   If you find yourself manually editing properties, that indicates a
missing feature - please file an issue!

   • Core GTD Properties

        • ORG_GTD

          *Used on*: All GTD items (projects, actions, calendar items,
          tickler items, etc.)

          *Purpose*: Identifies the type of GTD item

          *Values*:
          ‘"Projects"’
               Project heading
          ‘"Actions"’
               Project tasks and single actions
          ‘"Calendar"’
               Calendar items (appointments, deadlines)
          ‘"Tickler"’
               Items with specific review dates (time-based reminders)
          ‘"Someday"’
               Someday/maybe items (no specific timeframe)
          ‘"Delegated"’
               Delegated tasks (set in combination with DELEGATED_TO)

          *Example*:
               * My Project
               :PROPERTIES:
               :ORG_GTD: Projects
               :END:
               ** NEXT Task 1
               :PROPERTIES:
               :ORG_GTD: Actions
               :END:

          *Note*: This property is how org-gtd identifies items.  Don't
          modify manually unless you understand the implications.

        • ORG_GTD_REFILE

          *Used on*: Category headings that serve as refile targets

          *Purpose*: Marks a heading as a refile target for org-gtd's
          optional refile system (see *note Refiling section: Refiling
          to the appropriate area.)

          *Values*:
          ‘"Projects"’
               Target for refiling projects
          ‘"Actions"’
               Target for refiling single actions
          ‘"Calendar"’
               Target for refiling calendar items
          ‘"Tickler"’
               Target for refiling tickler items (time-based reminders)
          ‘"Someday"’
               Target for refiling someday/maybe items
          ‘"Habits"’
               Target for refiling habits

          *Multivalue support*: Values can be space-separated to accept
          multiple types.  For example, ‘Actions Projects’ makes a
          heading a valid target for both single actions and projects.

          *Example*:
               * Projects         <-- Can be at any level in any file
               :PROPERTIES:
               :ORG_GTD_REFILE: Projects
               :END:

               * Work/Development Projects   <-- Can have multiple targets per type
               :PROPERTIES:
               :ORG_GTD_REFILE: Projects
               :END:

               * Work Tasks      <-- Accepts multiple types
               :PROPERTIES:
               :ORG_GTD_REFILE: Actions Projects
               :END:

          *How it's set*:
             • Automatically created by ‘org-gtd-upgrade-v3-to-v4’
               (renames ORG_GTD on level 1 headings)
             • Manually when creating custom refile targets
             • Via ‘org-entry-put’ in elisp: ‘(org-entry-put nil
               "ORG_GTD_REFILE" "Projects")’

          *Important notes*:
             • Org-gtd merges these targets with your
               ‘org-refile-targets’ configuration
             • Can exist at ANY level in ANY file in ‘org-agenda-files’
             • You can have multiple refile targets for the same
               category type
             • A single heading can accept multiple types
               (space-separated values)
             • Your ‘org-refile-targets’ appear first, then
               ‘ORG_GTD_REFILE’ targets

   • Project Properties

        • ORG_GTD_FIRST_TASKS

          *Used on*: Project headings

          *Purpose*: Identifies which tasks can start immediately (have
          no dependencies)

          *Format*: Space-separated list of task IDs

          *Example*:
               * Software Release
               :PROPERTIES:
               :ORG_GTD: Projects
               :ORG_GTD_FIRST_TASKS: abc123 def456
               :END:

          This means tasks with IDs "abc123" and "def456" can both start
          immediately (parallel execution).

          *How it's set*:
             • Automatically when organizing a project
             • Automatically by graph view ‘r’ (add root task) and ‘b’
               (add blocker as root)
             • Programmatically via
               ‘org-entry-add-to-multivalued-property’

          *For interactive use*: Use graph view commands instead of
          editing this property directly.

   • Task Dependency Properties

        • ORG_GTD_DEPENDS_ON

          *Used on*: Project tasks

          *Purpose*: Lists task IDs that must complete before this task
          can start

          *Format*: Space-separated list of task IDs

          *Example*:
               ** NEXT Get project approval
               :PROPERTIES:
               :ID: task-001
               :ORG_GTD: Actions
               :ORG_GTD_BLOCKS: task-002 task-003
               :END:
               ** TODO Design solution
               :PROPERTIES:
               :ID: task-002
               :ORG_GTD: Actions
               :ORG_GTD_DEPENDS_ON: task-001
               :ORG_GTD_BLOCKS: task-004
               :END:
               ** TODO Setup infrastructure
               :PROPERTIES:
               :ID: task-003
               :ORG_GTD: Actions
               :ORG_GTD_DEPENDS_ON: task-001
               :ORG_GTD_BLOCKS: task-004
               :END:
               ** TODO Implement feature
               :PROPERTIES:
               :ID: task-004
               :ORG_GTD: Actions
               :ORG_GTD_DEPENDS_ON: task-002 task-003
               :END:

          In this example:
             • Task 001 (approval) starts first
             • Tasks 002 (design) and 003 (infrastructure) can run in
               parallel after approval
             • Task 004 (implement) waits for both 002 and 003 to
               complete

          *How it's set*:
             • Graph view: ‘s’ (add successor), ‘b’ (add blocker), ‘B’
               (modify blockers)
             • Text commands: ‘org-gtd-task-add-blockers’,
               ‘org-gtd-task-add-dependent’
             • Programmatically: ‘org-gtd-dependencies-create’
               (maintains bidirectional relationships)

          *For interactive use*: Use graph view or text-based task
          commands instead of editing this property directly.

        • ORG_GTD_BLOCKS

          *Used on*: Project tasks

          *Purpose*: Lists task IDs that depend on this task completing
          (inverse of DEPENDS_ON)

          *Format*: Space-separated list of task IDs

          *Relationship*: If task A has ‘ORG_GTD_BLOCKS: B C’, then:
             • Task B should have ‘ORG_GTD_DEPENDS_ON: A’
             • Task C should have ‘ORG_GTD_DEPENDS_ON: A’

          *How it's set*:
             • Automatically maintained when setting ORG_GTD_DEPENDS_ON
               (bidirectional)
             • Programmatically via ‘org-gtd-dependencies-create’
               (handles bidirectional updates)

          *For interactive use*: Use graph view or text-based task
          commands - they maintain the bidirectional relationship
          automatically.

        • ORG_GTD_PROJECT_IDS

          *Used on*: Tasks

          *Purpose*: Lists project IDs this task belongs to (supports
          multi-project tasks)

          *Format*: Space-separated list of project IDs

          *Note*: Currently org-gtd creates one project per task, but
          this property supports future multi-project features.

   • Calendar and Time Properties

        • ORG_GTD_TIMESTAMP

          *Used on*: Calendar items, delegated items

          *Purpose*: Stores the appointment time or follow-up date

          *Format*: Org timestamp (inactive timestamp)

          *Example*:
               * Doctor appointment
               :PROPERTIES:
               :ORG_GTD: Calendar
               :ORG_GTD_TIMESTAMP: [2025-10-15 Wed 14:00]
               :END:

          *Why not use SCHEDULED*: org-gtd uses a custom property to
          distinguish between "do this at this time" (GTD calendar
          items) and "start working on this sometime after this date"
          (org-mode scheduling).

          *How it's set*:
             • Automatically by ‘org-gtd-organize’ when organizing items
               as calendar items
             • Programmatically when creating calendar items

          *For interactive use*: Use ‘org-gtd-organize’ to change
          calendar items.

   • Delegation Properties

        • DELEGATED_TO

          *Used on*: Delegated items

          *Purpose*: Stores the name of person/team the task is
          delegated to

          *Format*: String (person's name)

          *Example*:
               * Review document
               :PROPERTIES:
               :ORG_GTD: Delegated
               :DELEGATED_TO: Alice Smith
               :ORG_GTD_TIMESTAMP: [2025-10-18 Fri]
               :END:

          *How it's set*:
             • Automatically by ‘org-gtd-organize’ when organizing as
               delegated item
             • Automatically by ‘org-gtd-delegate-agenda-item’ from
               agenda
             • Programmatically when creating delegated items

          *For interactive use*: Use ‘org-gtd-delegate-agenda-item’ or
          organize flow.

          *Customization*: Set ‘org-gtd-delegate-read-func’ to customize
          how names are entered (e.g., for completion).

   • Habit Properties

        • STYLE

          *Used on*: Habits

          *Purpose*: Identifies item as an org-mode habit

          *Value*: ‘"habit"’

          *Example*:
               * TODO Exercise
               SCHEDULED: <2025-10-11 Fri .+1d>
               :PROPERTIES:
               :STYLE: habit
               :END:

          *Note*: This is a standard org-mode habit property.  See
          org-mode documentation for habit repeat patterns and
          configuration.

   • Area of Focus Properties

        • CATEGORY

          *Used on*: All items (when using areas of focus)

          *Purpose*: Identifies which area of focus (GTD Horizon 2) an
          item belongs to

          *Format*: String matching value from ‘org-gtd-areas-of-focus’

          *Example*:
               * Finish quarterly report
               :PROPERTIES:
               :ORG_GTD: Actions
               :CATEGORY: Work
               :END:

          *When to set*:
             • During organize, if ‘org-gtd-set-area-of-focus’ is in
               ‘org-gtd-organize-hooks’
             • Manually with
               ‘org-gtd-area-of-focus-set-on-item-at-point’
             • From agenda with
               ‘org-gtd-area-of-focus-set-on-agenda-item’

          *Use*: Filter views by area with
          ‘org-gtd-reflect-area-of-focus’ or custom views.

   • Standard Org Properties Used by org-gtd

        • ID

          *Used on*: All GTD items

          *Purpose*: Unique identifier for the item (org-mode standard)

          *Format*: Auto-generated UUID

          *Note*: org-gtd relies heavily on IDs for task relationships.
          Don't delete ID properties.

        • *TODO* keyword

          *Not a property, but a heading keyword*

          *Values used by org-gtd*:
             • Value from ‘org-gtd-keyword-mapping’'s ‘todo’ key
               (default "TODO")
             • Value from ‘org-gtd-keyword-mapping’'s ‘next’ key
               (default "NEXT")
             • Value from ‘org-gtd-keyword-mapping’'s ‘wait’ key
               (default "WAIT")
             • Value from ‘org-gtd-keyword-mapping’'s ‘done’ key
               (default "DONE")
             • Value from ‘org-gtd-keyword-mapping’'s ‘canceled’ key
               (default "CNCL")

        • SCHEDULED (org-mode standard)

          *Used on*: Habits primarily

          *Purpose*: For org-mode habits, defines repeat pattern

          *Note*: org-gtd uses ORG_GTD_TIMESTAMP for calendar items
          instead of SCHEDULED to maintain GTD semantics.

        • DEADLINE (org-mode standard)

          *Used on*: Items with hard deadlines

          *Purpose*: Mark items that must be done by a specific date

          *Note*: org-gtd respects org-mode deadlines in all views and
          oops checks.


File: org-gtd.info,  Node: Troubleshooting Projects,  Next: View DSL Filter Reference,  Prev: Properties Reference (Internal Implementation),  Up: Reference

1.5.4 Troubleshooting Projects
------------------------------

This section covers how to fix problems with project dependencies.  *You
should rarely need this* - the graph view and task management commands
handle dependencies correctly.  If you find yourself needing these
troubleshooting steps frequently, that indicates a bug - please file an
issue!

   • Fixing Broken Dependencies

     If you encounter dependency problems (circular dependencies, broken
     references, orphaned tasks):

       1. *Validate project structure*:
             • Put point on project heading
             • Run ‘M-x org-gtd-validate-project-dependencies’
             • This detects broken references, orphaned tasks, and
               circular dependencies
             • Follow the guidance provided

       2. *Visual inspection with graph view*:
             • Run ‘M-x org-gtd-show-project-graph’
             • Visual inspection often makes problems obvious
             • Missing arrows?  Use ‘s’ to add successor or ‘B’ to add
               blockers
             • Wrong arrows?  Use ‘B’ or ‘S’ to uncheck incorrect
               relationships
             • Use ‘i’ to inspect a task's current relationships

       3. *Clear and rebuild*: If task relationships are completely
          corrupted:
             • In graph view: Select task, use ‘B’ and ‘S’ to adjust
               blockers/dependents
             • Or in text: Run ‘M-x org-gtd-task-clear-relationships’
             • Rebuild using graph view: ‘s’ (add successor), ‘b’ (add
               blocker)

   • When Manual Property Editing is Needed

     *You should never need to manually edit properties during normal
     use.*

     The ONLY cases where manual property editing might be necessary:

       1. *Writing elisp automation/integration code*
             • See *note Properties Reference: Properties Reference
               (Internal Implementation). for property documentation
             • Use programmatic functions:
               ‘org-gtd-dependencies-create’,
               ‘org-entry-add-to-multivalued-property’, etc.
             • Never manipulate properties directly from interactive
               commands

       2. *Debugging org-gtd internals*
             • If you suspect a bug in org-gtd's property management
             • Compare properties with graph view to identify
               discrepancies
             • File an issue with details!

       3. *Migrating data from another system*
             • If importing projects from external tools
             • Batch property updates may be more efficient
             • Validate with ‘org-gtd-validate-project-dependencies’
               afterward

       4. *Emergency recovery from data corruption*
             • Only as last resort if graph view and commands fail
             • After manual edits, run
               ‘org-gtd-projects-fix-todo-keywords-for-project-at-point’
               (one project)
             • Or run ‘org-gtd-projects-fix-all-todo-keywords’ to fix
               all projects at once
             • Consider this a bug and file an issue

     *If you find yourself manually editing properties regularly*, that
     indicates missing features.  Please file an issue describing your
     workflow - we'll add the missing commands!

   • Common Problems and Solutions

        • Project Shows No NEXT Tasks (Stuck Project)

          *Symptom*: Project has incomplete tasks but none are NEXT.

          *Diagnosis*:
             • Run ‘M-x org-gtd-show-project-graph’
             • Look for blue boxes (NEXT tasks)
             • If no blue boxes, check for:
                  • Circular dependencies (arrows forming a loop)
                  • All tasks waiting on incomplete tasks
                  • Missing ORG_GTD_FIRST_TASKS property

          *Solution*:
             • Fix circular dependencies: Use ‘B’ to remove incorrect
               blocker relationships
             • Add root tasks: Use ‘r’ to create tasks that can start
               immediately
             • Run ‘org-gtd-validate-project-dependencies’ for detailed
               diagnosis

        • Too Many NEXT Tasks

          *Symptom*: Project shows 10+ blue boxes in graph view.

          *Diagnosis*: Tasks that should be dependent are independent.

          *Solution*:
             • In graph view, identify tasks that should depend on
               others
             • Select a task, use ‘B’ to add blockers it should wait for
             • Or use ‘s’ from an earlier task to add a successor that
               should come later

        • Task Won't Advance to NEXT

          *Symptom*: Completed a task, but dependent task still shows
          TODO (orange).

          *Diagnosis*:
             • In graph view, select the orange task
             • Press ‘i’ to show relationships
             • Check if all blockers are actually DONE

          *Solution*:
             • If blockers are DONE but showing as blocking: Press ‘g’
               to refresh graph
             • If blocker shouldn't block this task: Use ‘B’ to modify
               blockers and uncheck it
             • If many wrong dependencies: Run
               ‘org-gtd-task-clear-relationships’, rebuild with ‘s~/~b’

        • Task States Inconsistent After External Edits

          *Symptom*: After editing on mobile app or resolving sync
          conflicts, task states don't match dependencies.

          *Examples*:
             • Tasks marked NEXT but blocked by incomplete dependencies
             • Tasks stuck in TODO when they should be NEXT
             • Multiple projects showing inconsistent states

          *Diagnosis*:
             • External tools (mobile apps, web interfaces) don't
               understand org-gtd dependency logic
             • Manual edits or sync conflicts disrupted task states
             • Affects all projects if you edited multiple files

          *Solution*:
             • For one project: Put point on project heading, run ‘M-x
               org-gtd-projects-fix-todo-keywords-for-project-at-point’
             • For all projects: Run ‘M-x
               org-gtd-projects-fix-all-todo-keywords’

          *Recommended workflow after mobile edits*:
            1. Sync files to Emacs
            2. Run ‘M-x org-gtd-projects-fix-all-todo-keywords’
            3. Verify with ‘M-x org-gtd-engage’ - should show correct
               NEXT tasks


File: org-gtd.info,  Node: View DSL Filter Reference,  Next: Hooks Framework Reference,  Prev: Troubleshooting Projects,  Up: Reference

1.5.5 View DSL Filter Reference
-------------------------------

Build custom agenda views in minutes.  The View DSL lets you filter your
GTD items by type, time, area of focus, and more--using simple
declarative syntax instead of writing skip functions.

   *For:* GTD users who want views beyond the built-in ‘org-gtd-engage’
and ‘org-gtd-reflect-*’ commands.

   • Your First Custom View in 60 Seconds

     Try this now:

       1. Evaluate this code (select it and run ‘M-x eval-region’):

               (org-gtd-view-show
                '((name . "My Delegated Items")
                  (type . delegated)))

       2. An agenda view appears showing all your delegated items

       3. Try changing ‘delegated’ to ‘next-action’ and re-evaluate--now
          you see NEXT actions

     That's it.  You just created a custom view.  The rest of this
     section shows you what else you can filter by.

   • Understanding View Specs

     A view spec is a simple list describing what you want to see:

          '((name . "View Name")     ;; What appears in the agenda header
            (type . delegated)       ;; Filter: show only delegated items
            (when . past))           ;; Filter: only items with past dates

     *Mental model:* Think of each line as a filter.  Items must pass
     ALL filters to appear.  ‘(type . delegated)’ means "only delegated
     items".  Adding ‘(when . past)’ means "only delegated items whose
     check-in date has passed".

        • Combining Filters

          Filters stack with AND logic:

               ;; Delegated items + past due = missed check-ins
               '((name . "Missed Check-ins")
                 (type . delegated)
                 (when . past))

               ;; Projects + specific area = focused view
               '((name . "Work Projects")
                 (type . active-project)
                 (area-of-focus . "Work"))

        • Multi-Block Views

          Show multiple filtered lists in one view:

               '((name . "My Dashboard")
                 (blocks . (((name . "Calendar Today")
                             (type . calendar)
                             (when . today))
                            ((name . "Delegated Due")
                             (type . delegated)
                             (when . past))
                            ((name . "NEXT Actions")
                             (type . next-action)))))

          Each block is its own filter.  The view shows them stacked as
          separate sections.

   • Common Patterns

        • Weekly Review View

          See what needs attention:

               (defun my-weekly-review ()
                 "Show stuck projects, missed items, and recent completions."
                 (interactive)
                 (org-gtd-view-show
                  '(((name . "Stuck Projects")
                     (type . stuck-project))
                    ((name . "Missed Delegated")
                     (type . delegated)
                     (when . past))
                    ((name . "Completed This Week")
                     (done . past-week)))))

        • Morning Planning View

          Start your day focused:

               (defun my-morning-view ()
                 "Calendar, delegated check-ins, and NEXT actions."
                 (interactive)
                 (org-gtd-view-show
                  '((name . "Morning Planning")
                    (blocks . (((name . "Today's Schedule")
                                (block-type . calendar-day))
                               ((name . "Check-ins Due")
                                (type . delegated)
                                (when . today))
                               ((name . "Ready to Work On")
                                (type . next-action)))))))

        • Area of Focus View

          Filter everything by life area:

               (defun my-work-view ()
                 "All work-related active items."
                 (interactive)
                 (org-gtd-view-show
                  '(((name . "Work Projects")
                     (type . active-project)
                     (area-of-focus . "Work"))
                    ((name . "Work NEXT Actions")
                     (type . next-action)
                     (area-of-focus . "Work"))
                    ((name . "Work Delegated")
                     (type . delegated)
                     (area-of-focus . "Work")))))

   • Filter Reference

     The following sections document all available filters.  Use them to
     build the exact view you need.

        • View Structure

          A GTD view is defined as an alist with filters at the top
          level:

               ;; Simple view with filters at top level
               '((name . "View Name")
                 (type . delegated)
                 (when . past))

          Multiple filters create AND logic (all must match).

             • Multi-Block Views

               For complex views with multiple sections (like the engage
               view), use ‘blocks’:

                    '((name . "My Custom Dashboard")
                      (blocks . (((name . "Today's Calendar")
                                  (block-type . calendar-day))
                                 ((name . "Items Due Today")
                                  (type . delegated)
                                  (when . today))
                                 ((name . "All NEXT Actions")
                                  (type . next-action)))))

               Each block is its own view spec.  Blocks are displayed in
               order as separate agenda sections.

             • Block Types

               Special ‘block-type’ values control how blocks are
               rendered:

               ‘calendar-day’
                    Native org-agenda day view filtered to Calendar and
                    Habit items only
               ‘todo’
                    Native org-agenda todo block (requires
                    ‘todo-keyword’)
               _default_
                    tags block with skip function (when no block-type
                    specified)

             • Native Blocks (Escape Hatch)

               Have you ever wanted your NEXT actions sorted by
               priority?  Or needed a custom skip function for a
               specialized workflow?  The DSL handles most cases, but
               org-agenda has decades of features.  When you hit its
               limits, ‘native’ blocks let you drop down to raw
               org-agenda syntax--without abandoning the DSL entirely.

                  • When You'll Need This

                    You're building a view and think: "I wish I could
                    sort these by effort" or "I need my custom skip
                    function here."  The DSL doesn't support sorting
                    yet.  What do you do?

                    You have two choices:
                      1. Write the whole view in
                         ‘org-agenda-custom-commands’ (losing DSL
                         benefits)
                      2. Use a ‘native’ block for just that section
                         (keeping DSL for the rest)

                    Option 2 is what this section teaches.

                  • Your First Native Block

                    Start with something you know.  This DSL block shows
                    NEXT actions:

                         ((type . next-action))

                    Here's the equivalent as a native block:

                         ((native . (tags-todo "LEVEL>0+ORG_GTD=\"Actions\"/NEXT" nil)))

                    The format is ‘(BLOCK-TYPE MATCH-STRING
                    SETTINGS)’--exactly what
                    ‘org-agenda-custom-commands’ uses.  Try evaluating
                    both in a multi-block view:

                         (org-gtd-view-show
                          '((name . "Comparing DSL and Native")
                            (blocks . (((name . "DSL Version")
                                        (type . next-action))
                                       ((native . (tags-todo "LEVEL>0+ORG_GTD=\"Actions\"/NEXT"
                                                   ((org-agenda-overriding-header "Native Version")))))))))

                    They show the same items.  The native block is more
                    verbose, but it unlocks org-agenda's full power.

                  • Adding Custom Sorting

                    Now the payoff.  Want priority sorting?  Add it to
                    the settings list:

                         ((native . (tags-todo "+@work/NEXT"
                                     ((org-agenda-sorting-strategy '(priority-down effort-up))
                                      (org-agenda-overriding-header "Work by Priority")))))

                    The settings list can include any org-agenda
                    variable.  Common ones:
                       • ‘org-agenda-sorting-strategy’ -- Sort by
                         priority, effort, alphabetically
                       • ‘org-agenda-skip-function’ -- Your custom skip
                         logic
                       • ‘org-agenda-prefix-format’ -- Custom prefix
                         display

                  • Mixing DSL and Native

                    The real power is mixing them.  Use DSL for simple
                    blocks, native for complex ones:

                         (org-gtd-view-show
                          '((name . "Mixed Dashboard")
                            (blocks . (((type . delegated)                               ; DSL: simple
                                        (when . past))
                                       ((native . (tags-todo "+urgent"                   ; Native: sorted
                                                   ((org-agenda-sorting-strategy '(effort-up))
                                                    (org-agenda-overriding-header "Urgent by Effort")))))
                                       ((type . next-action))))))                        ; DSL: simple

                    Each block is independent.  Use whatever syntax fits
                    that block's needs.

                  • Native Block Types

                    The BLOCK-TYPE (first element) determines what kind
                    of agenda block you get:

                    Block Type    What It Shows
                    -------------------------------------------------------
                    ‘agenda’      Calendar/timeline (like daily view)
                    ‘todo’        TODO items by keyword
                    ‘tags’        Items matching tag/property expression
                    ‘tags-todo’   Like ‘tags’ but only TODO items
                    ‘search’      Full-text search results

                  • Quick Reference

                    *Syntax*:
                         ((native . (BLOCK-TYPE MATCH-STRING SETTINGS)))

                    *Rules*:
                       • Only valid inside a ‘blocks’ list
                       • Other DSL keys in the same block spec are
                         ignored
                       • Settings is an alist of ‘(org-agenda-variable
                         value)’ pairs

                    *When to use*: Custom sorting, skip functions,
                    specialized org-agenda settings, or migrating
                    complex views incrementally

   • Type Filters

     Filter by GTD item type:

        • ‘(type . delegated)’

          *Matches*: Items with ‘ORG_GTD="Delegated"’ and TODO keyword
          ‘WAIT’

          *Use case*: See all delegated tasks

          *Example*:
               '((name . "All Delegations")
                 (type . delegated))

        • ‘(type . calendar)’

          *Matches*: Items with ‘ORG_GTD="Calendar"’

          *Use case*: See all calendar items/appointments

          *Example*:
               '((name . "Calendar Items")
                 (type . calendar))

        • ‘(type . project)’

          *Matches*: Project headings (‘ORG_GTD="Projects"’)

          *Use case*: List all projects

          *Example*:
               '((name . "All Projects")
                 (type . project))

        • ‘(type . active-project)’

          *Matches*: Projects with at least one active (non-done) task

          *Use case*: See projects with work remaining

          *Example*:
               '((name . "Active Projects")
                 (type . active-project))

        • ‘(type . completed-project)’

          *Matches*: Projects where all tasks are DONE

          *Use case*: Weekly review to see completed projects ready to
          archive

          *Example*:
               '((name . "Completed Projects")
                 (type . completed-project))

        • ‘(type . stuck-project)’

          *Matches*: Projects with active tasks but no NEXT or WAIT
          tasks

          *Use case*: Find projects needing attention (dependency
          problems)

          *Example*:
               '((name . "Stuck Projects")
                 (type . stuck-project))

        • ‘(type . tickler)’

          *Matches*: Items with ‘ORG_GTD="Tickler"’ (time-based
          reminders with review dates)

          *Use case*: Review tickler items

          *Example*:
               '((name . "Tickler Items")
                 (type . tickler))

        • ‘(type . someday)’

          *Matches*: Items with ‘ORG_GTD="Someday"’ (someday/maybe with
          no specific timeframe)

          *Use case*: Review someday/maybe list

          *Example*:
               '((name . "Someday/Maybe")
                 (type . someday))

        • ‘(type . habit)’

          *Matches*: Items with ‘ORG_GTD="Habits"’

          *Use case*: See all habits

          *Example*:
               '((name . "All Habits")
                 (type . habit))

        • ‘(type . next-action)’

          *Matches*: Single action items (‘ORG_GTD="Actions"’) with TODO
          keyword ‘NEXT’

          *Use case*: See all single actions (not project tasks)

          *Example*:
               '((name . "Single Actions")
                 (type . next-action))

        • ‘(type . tickler-project)’

          *Matches*: Projects that were moved to tickler (paused with
          review dates)

          *Use case*: Review tickler projects during weekly review

          *Note*: Consider using ‘incubated-project’ instead, which
          covers both tickler projects and someday/maybe projects.

          *Example*:
               '((name . "Tickler Projects")
                 (type . tickler-project))

        • ‘(type . incubated-project)’

          *Matches*: Projects that were moved to tickler OR
          someday/maybe (paused projects)

          *Use case*: Review all incubated projects during
          weekly/monthly review.  This includes both tickler projects
          (with review dates) and someday/maybe projects (indefinitely
          paused).

          *Example*:
               '((name . "Incubated Projects")
                 (type . incubated-project))

        • ‘(type . stuck-delegated)’

          *Matches*: Delegated items missing required metadata
          (invalid/missing timestamp OR missing "who")

          *Use case*: Find delegated items needing attention during
          weekly review

          *Example*:
               '((name . "Stuck Delegated Items")
                 (type . stuck-delegated))

        • ‘(type . stuck-calendar)’

          *Matches*: Calendar items missing a valid timestamp

          *Use case*: Find calendar items that need a date set

          *Example*:
               '((name . "Stuck Calendar Items")
                 (type . stuck-calendar))

        • ‘(type . stuck-tickler)’

          *Matches*: Tickler items missing a valid review date

          *Use case*: Find tickler items that need a review date

          *Example*:
               '((name . "Stuck Tickler Items")
                 (type . stuck-tickler))

        • ‘(type . stuck-habit)’

          *Matches*: Habit items missing a valid scheduled date

          *Use case*: Find habits that need a schedule

          *Example*:
               '((name . "Stuck Habits")
                 (type . stuck-habit))

   • Time-based Filters

     Filter by timestamps, deadlines, and scheduled dates.

        • Semantic Time: ‘(when . VALUE)’

          The ‘when’ filter provides semantic time filtering that
          automatically uses the correct timestamp property for each GTD
          item type:

             • For ‘delegated’ and ‘calendar’ types: checks
               ‘ORG_GTD_TIMESTAMP’
             • For ‘tickler’ type: checks the tickler review date

          Values: ‘today’, ‘past’, ‘future’

          *Example*: Delegated items due today:
               '((name . "Delegated Check-ins Today")
                 (type . delegated)
                 (when . today))

          *Example*: Missed calendar appointments:
               '((name . "Missed Appointments")
                 (type . calendar)
                 (when . past))

          *Example*: Upcoming delegated check-ins:
               '((name . "Upcoming Delegated")
                 (type . delegated)
                 (when . future))

        • Deadline: ‘(deadline . VALUE)’

          Filter by org-mode DEADLINE.

          Values: ‘past’, ‘future’, ‘today’

          *Example*:
               '((name . "Overdue Items")
                 (deadline . past))

        • Scheduled: ‘(scheduled . VALUE)’

          Filter by org-mode SCHEDULED.

          Values: ‘past’, ‘future’, ‘today’

          *Example*:
               '((name . "Today's Scheduled Items")
                 (scheduled . today))

   • *TODO* Keyword Filters

     Filter by TODO state.

     *Note*: The ‘type’ filter automatically includes the correct TODO
     keyword for each type (e.g., ‘next-action’ includes ‘NEXT’,
     ‘delegated’ includes ‘WAIT’).  Use these filters only when you need
     explicit control.

        • ‘(todo . ("KEYWORD1" "KEYWORD2"))’

          *Matches*: Items with any of the specified TODO keywords

          *Use case*: Show specific states

          *Example*: Show only NEXT actions:
               '((name . "NEXT Actions Only")
                 (todo . ("NEXT")))

          *Example*: Show NEXT and WAIT:
               '((name . "Active and Waiting")
                 (todo . ("NEXT" "WAIT")))

        • ‘(done . VALUE)’

          *Matches*: Items with done TODO states (right side of ‘|’ in
          keyword sequence)

          *Values*:
          ‘t’
               Any done item, regardless of when closed
          ‘NUMBER’
               Done in last NUMBER days (e.g., ‘14’ for last 2 weeks)
          ‘today’
               Done today
          ‘recent’
               Done in last 7 days
          ‘past-day’
               Done in last day
          ‘past-week’
               Done in last week
          ‘past-month’
               Done in last month
          ‘past-year’
               Done in last year

          *Use case*: Show completed items, optionally filtered by when
          they were completed

          *Example*: All completed items:
               '((name . "Completed Items")
                 (done . t))

          *Example*: Items completed this week:
               '((name . "Completed This Week")
                 (done . past-week))

          *Example*: Items completed in the last 14 days:
               '((name . "Completed in Last 2 Weeks")
                 (done . 14))

          *Example*: Items completed today:
               '((name . "Completed Today")
                 (done . today))

   • Area of Focus Filters

     Filter by life area:

        • ‘(area-of-focus . "AREA")’

          *Matches*: Items with ‘CATEGORY="AREA"’

          *Use case*: Focus on specific life area

          *Example*:
               '((name . "Work Items")
                 (area-of-focus . "Work"))

          *Example*: Work projects only:
               '((name . "Work Projects")
                 (type . active-project)
                 (area-of-focus . "Work"))

   • Tag Filters

     Filter by org tags:

        • ‘(tags . ("TAG1" "TAG2"))’

          *Matches*: Items with any of the specified tags

          *Use case*: Filter by context, priority, or custom tags

          *Example*:
               '((name . "Home and Errands")
                 (type . next-action)
                 (tags . ("@home" "@errands")))

        • ‘(tags-match . "PATTERN")’

          *Matches*: Items matching org-mode tag expression pattern

          *Use case*: Complex tag queries

          *Example*: All items with context tags (tags starting with @):
               '((name . "Context-Tagged Items")
                 (tags-match . "{^@}"))

          *Org tag expressions*:
          ‘"tag1|tag2"’
               Has tag1 OR tag2
          ‘"tag1&tag2"’
               Has tag1 AND tag2
          ‘"{^@}"’
               Has any tag starting with @

   • Priority, Effort, and Clocked Filters

     Filter by task metadata useful for "quick wins", "deep work", and
     triage views.

        • ‘(priority . VALUE)’

          *Matches*: Items with matching priority

          *Forms*:
          ‘(priority . A)’
               Single value--matches priority A
          ‘(priority . (A B))’
               List--matches priority A OR B
          ‘(priority . (>= B))’
               Comparison--matches B or higher (A, B)
          ‘(priority . nil)’
               Items with no priority set

          *Comparison operators*: ‘<’, ‘>’, ‘<=’, ‘>=’

          *Note*: A is highest priority (A > B > C). Respects
          ‘org-priority-highest’ and ‘org-priority-lowest’ for custom
          ranges.

          *Example*: High priority actions:
               '((name . "High Priority")
                 (type . next-action)
                 (priority . A))

          *Example*: Important items (A or B):
               '((name . "Important Tasks")
                 (type . next-action)
                 (priority . (A B)))

          *Example*: All items B or higher:
               '((name . "Priority B+")
                 (type . next-action)
                 (priority . (>= B)))

          *Example*: Triage items missing priority:
               '((name . "Needs Priority")
                 (type . next-action)
                 (priority . nil))

        • ‘(effort . SPEC)’

          *Matches*: Items with matching Effort property

          *Forms*:
          ‘(effort . (< "0:30"))’
               Under 30 minutes
          ‘(effort . (> "1:00"))’
               Over 1 hour
          ‘(effort . (between "0:15" "1:00"))’
               Range (inclusive)
          ‘(effort . nil)’
               Items with no effort estimate

          *Duration formats* (all org-mode formats supported):
          ‘"3:12"’
               H:MM
          ‘"1:23:45"’
               H:MM:SS
          ‘"1d3h5min"’
               Units (d, h, min)
          ‘"30"’
               Bare number (minutes)

          *Example*: Quick wins (under 15 minutes):
               '((name . "Quick Wins")
                 (type . next-action)
                 (effort . (< "15min")))

          *Example*: Deep work items (1-2 hours):
               '((name . "Deep Work")
                 (type . next-action)
                 (effort . (between "1:00" "2:00")))

          *Example*: Triage items missing effort:
               '((name . "Needs Effort Estimate")
                 (type . next-action)
                 (effort . nil))

        • ‘(clocked . SPEC)’

          *Matches*: Items with matching total clocked time

          *Forms*:
          ‘(clocked . (< "0:30"))’
               Less than 30 minutes clocked
          ‘(clocked . (> "2:00"))’
               More than 2 hours invested
          ‘(clocked . (between "0:30" "2:00"))’
               Range (inclusive)
          ‘(clocked . nil)’
               Items with no time clocked (0 minutes)

          *Use case*: Find items you've already invested time in, or
          items you haven't started yet.

          *Example*: Items with significant time invested:
               '((name . "Deep in Progress")
                 (type . next-action)
                 (clocked . (> "1:00")))

          *Example*: Not started yet:
               '((name . "Not Started")
                 (type . next-action)
                 (clocked . nil))

          *Example*: Focus work (high priority, time invested):
               '((name . "Focus Work")
                 (type . next-action)
                 (priority . (>= B))
                 (clocked . (> "0:30")))

        • ‘(last-clocked-out . SPEC)’

          *Matches*: Items based on when they were last clocked out

          *Forms*:
          ‘(last-clocked-out . (> "2d"))’
               Not worked on in 2+ days
          ‘(last-clocked-out . (>= "2d"))’
               Not worked on in 2+ days (inclusive)
          ‘(last-clocked-out . (< "1w"))’
               Worked on within past week
          ‘(last-clocked-out . (<= "1w"))’
               Worked on in past week (inclusive)
          ‘(last-clocked-out . nil)’
               Never clocked

          *Duration formats*:
          ‘"2d"’
               2 days
          ‘"1w"’
               1 week
          ‘"3h"’
               3 hours
          ‘"30m"’
               30 minutes

          *Project handling*: For project headings, automatically checks
          all tasks in the project and uses the most recent clock-out
          time.

          *Example*: Find stale projects not worked on in a week:
               '((name . "Stale Projects")
                 (type . project)
                 (last-clocked-out . (> "1w")))

          *Example*: Find items never started:
               '((name . "Never Started")
                 (type . next-action)
                 (last-clocked-out . nil))

   • Property Filters

     Filter by arbitrary org properties:

        • ‘(property . (("PROP" . "VALUE")))’

          *Matches*: Items with specified property value

          *Use case*: Filter by custom properties

          *Example*:
               '((name . "High Priority Actions")
                 (property . (("PRIORITY" . "A")))
                 (type . next-action))

   • Structural Filters

     Filter by org heading structure:

        • ‘(level . N)’

          *Matches*: Headings at level N

          *Use case*: Show only top-level items

          *Example*: Top-level projects only:
               '((name . "Top-Level Projects")
                 (type . project)
                 (level . 2))

          *Note*: org-gtd projects are typically at level 2 in their
          files (under a category heading at level 1).

   • Special Filters

        • ‘(not-habit . t)’

          *Matches*: Items that are NOT habits

          *Use case*: Exclude habits from views

          *Example*:
               '((name . "NEXT Actions (No Habits)")
                 (type . next-action)
                 (not-habit . t))

        • ‘(invalid-timestamp . t)’

          *Matches*: Items with missing or malformed ‘ORG_GTD_TIMESTAMP’
          property

          *Use case*: Data validation, finding broken calendar/delegate
          items

          *Example*:
               '((name . "Items with Invalid Timestamps")
                 (invalid-timestamp . t))

   • View Configuration Options

     These options control how the view is displayed:

        • ‘(block-type . TYPE)’

          *Purpose*: Control how a block is rendered

          *Values*:
          ‘calendar-day’
               Native org-agenda day view filtered to Calendar and Habit
               items
          ‘todo’
               Native org-agenda todo block (requires ‘todo-keyword’)
          _omit_
               Default tags block with skip function

          *Use case*: When you need native agenda features (time grid,
          habits, etc.)

          *Example*: Multi-block view with calendar:
               '((name . "My Dashboard")
                 (blocks . (((name . "Today's Schedule")
                             (block-type . calendar-day))
                            ((name . "Delegated Due Today")
                             (type . delegated)
                             (when . today)))))

        • ‘(blocks . BLOCK-LIST)’

          *Purpose*: Create a multi-section view with multiple blocks

          *Format*: List of view specs, each with its own name and
          filters

          *Example*:
               '((name . "Review Dashboard")
                 (blocks . (((name . "Stuck Projects")
                             (type . stuck-project))
                            ((name . "Missed Delegated")
                             (type . delegated)
                             (when . past))
                            ((name . "Upcoming Calendar")
                             (type . calendar)
                             (when . future)))))

        • Prefix DSL: Customizing the Task Prefix Column

          When you look at your engage view, you see context information
          on the left of each task--like the project name.  The Prefix
          DSL lets you control what appears there using a simple
          fallback chain.

          *Mental model:* Think of the prefix like a label maker.  You
          specify what you _want_ to show, in order of preference.
          org-gtd tries each option until one has a value.

             • Your First Prefix in 60 Seconds

               Try this now (evaluate with ‘M-x eval-region’):

                    (org-gtd-view-show
                     '((name . "Tasks with Context")
                       (prefix . (project area-of-focus "—"))
                       (type . next-action)))

               You'll see NEXT actions with:
                  • The project name (if the task is in a project)
                  • Or the area of focus (if no project, but area is
                    set)
                  • Or a dash "—" (if neither is available)

               That's the fallback chain in action.

             • ‘(prefix . (ELEMENT ...))’

               *Purpose*: Control what context appears before each task
               in the view

               *Format*: A list of elements, tried in order.  First
               non-empty value wins.

               *Available elements*:
               ‘project’
                    The project heading this task belongs to
               ‘area-of-focus’
                    The ‘CATEGORY’ property (your GTD area of focus)
               ‘file-name’
                    The base name of the file containing the task
               ‘"literal string"’
                    Any quoted string (used as fallback)

               *Example*: Show project, fallback to area, then to
               literal text:
                    '((name . "My View")
                      (prefix . (project area-of-focus "No Context"))
                      (type . next-action))

               *Example*: Just show the project name (or nothing):
                    '((name . "Project Tasks")
                      (prefix . (project))
                      (type . next-action))

               *Example*: Tickler items labeled "Incubated":
                    '((name . "Tickler Items")
                      (prefix . ("Incubated"))
                      (type . tickler))

             • ‘(prefix-width . N)’

               *Purpose*: Control how many characters the prefix column
               uses

               *Default*: Uses ‘org-gtd-prefix-width’ (default: 12)

               *Note*: Long values are truncated with
               ‘org-gtd-agenda-truncate-ellipsis’ (default "…").  Short
               values are padded with spaces.

               *Example*: Extra space for long project names:
                    '((name . "Wide Prefix View")
                      (prefix . (project area-of-focus))
                      (prefix-width . 20)
                      (type . next-action))

             • Prefix Inheritance in Multi-Block Views

               When you define ‘prefix’ at the view level, all blocks
               inherit it:

                    '((name . "My Dashboard")
                      (prefix . (project area-of-focus "—"))  ;; All blocks use this
                      (prefix-width . 15)
                      (blocks . (((name . "Calendar Today")
                                  (type . calendar)
                                  (when . today))
                                 ((name . "NEXT Actions")
                                  (type . next-action)))))

               Individual blocks can override the inherited prefix:

                    '((name . "Mixed Prefixes")
                      (prefix . (project))  ;; Default for blocks
                      (blocks . (((name . "Projects")
                                  (prefix . ("Project"))  ;; Override: literal label
                                  (type . active-project))
                                 ((name . "NEXT Actions")
                                  ;; Uses inherited (project) prefix
                                  (type . next-action)))))

             • Low-Level: ‘(prefix-format . FORMAT-STRING)’

               For advanced users who need full control, you can specify
               the raw org-agenda prefix format string.  This bypasses
               the prefix DSL.

               *Example*:
                    '((name . "Custom Format")
                      (prefix-format . " %i %-12:(org-gtd-agenda--resolve-prefix-chain '(project) 12) ")
                      (blocks . (((name . "NEXT Actions")
                                  (type . next-action)))))

               Most users should use ‘(prefix . ...)’ instead.

        • ‘(view-type . agenda)’

          *Purpose*: Create a day/week org-agenda view instead of a tags
          block

          *Use case*: When you want a standard day/week agenda view

          *Example*:
               '((name . "Weekly Agenda")
                 (view-type . agenda)
                 (agenda-span . 7))

        • ‘(agenda-span . N)’

          *Purpose*: Number of days to show in agenda view

          *Default*: 1

          *Requires*: ‘(view-type . agenda)’

   • Simplified Multi-Block Views

     Creating multi-block views usually requires verbose ‘blocks’
     syntax.  The View DSL offers a simpler alternative: just list the
     types you want to see.

     *For:* Users who want quick multi-block views without boilerplate.

        • The Problem: Verbose Block Definitions

          A typical area-of-focus review view requires this:

               ;; Verbose: every block needs explicit configuration
               '((name . "Health Review")
                 (blocks . (((name . "Projects")
                             (type . project)
                             (area-of-focus . "Health"))
                            ((name . "Next Actions")
                             (type . next-action)
                             (area-of-focus . "Health"))
                            ((name . "Calendar")
                             (type . calendar)
                             (area-of-focus . "Health")
                             (when . today)))))

          Notice the repetition: ‘area-of-focus’ appears in every block,
          and you had to remember that ‘calendar’ needs ‘(when .
          today)’.

        • The Solution: Implicit Blocks

          The same view, simplified:

               ;; Concise: types expand automatically with smart defaults
               '((name . "Health Review")
                 (area-of-focus . "Health")
                 (type . project)
                 (type . next-action)
                 (type . calendar))

          When you list multiple ‘type’ keys at the top level, org-gtd
          automatically:
            1. Creates a block for each type
            2. Inherits top-level filters (‘area-of-focus’) to all
               blocks
            3. Applies smart defaults (e.g., ‘calendar’ gets ‘(when .
               today)’)

        • Try It Now

          Evaluate this (select and run ‘M-x eval-region’):

               (org-gtd-view-show
                '((name . "Quick Dashboard")
                  (type . next-action)
                  (type . delegated)
                  (type . tickler)))

          You get three sections:
             • "Next Actions" - all your NEXT tasks
             • "Delegated" - items due today (smart default: ‘when .
               today’)
             • "Tickler" - reminders due today (smart default: ‘when .
               today’)

          No ‘blocks’ syntax.  No ‘when’ filters.  org-gtd inferred
          them.

        • Smart Type Defaults

          Time-sensitive types automatically filter to "today":

          Type              Default ‘when’   Default Name
          ------------------------------------------------------------------
          ‘calendar’        ‘today’          "Calendar"
          ‘delegated’       ‘today’          "Delegated"
          ‘tickler’         ‘today’          "Tickler"
          ‘habit’           --               "Habits"
          ‘next-action’     --               "Next Actions"
          ‘project’         --               "Projects"
          ‘someday’         --               "Someday/Maybe"
          ‘stuck-project’   --               "Projects (Needs Attention)"

          *Why these defaults?*  For calendar, delegated, and tickler
          items, you usually want to see what's relevant _today_.  For
          other types, you want to see everything.

        • Top-Level Inheritance

          Filters at the top level apply to _all_ blocks:

               '((name . "Work Focus")
                 (area-of-focus . "Work")  ;; Applied to all blocks
                 (type . project)
                 (type . next-action)
                 (type . delegated))

          This shows only Work-related items across all three sections.

        • The Four-Tier Precedence Model

          When org-gtd expands implicit blocks, it applies settings in
          this order (highest priority first):

            1. *Block-explicit* -- If you use explicit ‘blocks’ syntax
               and set a value, it wins
            2. *Top-level* -- Filters at the view's top level inherit to
               all blocks
            3. *Type smart default* -- Built-in defaults for that type
               (e.g., ‘calendar’ → ‘when . today’)
            4. *Global defaults* -- Package defaults like
               ‘org-gtd-prefix-width’

          *Example*: Override a smart default:

               ;; Show ALL calendar items, not just today
               '((name . "All Calendar")
                 (when . future)  ;; Top-level overrides type default
                 (type . calendar))

          *Example*: Mix explicit and implicit:

               '((name . "Mixed View")
                 (area-of-focus . "Work")
                 (type . next-action)  ;; Gets "Next Actions" name, Work filter
                 (type . delegated))   ;; Gets "Delegated" name, Work filter, when=today

        • When to Use Explicit Blocks

          Use explicit ‘blocks’ syntax when you need:
             • Custom block names (implicit blocks use default names)
             • Different filters per block (beyond inheritance)
             • Non-standard block types like ‘calendar-day’ or ‘todo’

          *Example*: Custom names require explicit blocks:

               '((name . "My Dashboard")
                 (blocks . (((name . "Today's Schedule")  ;; Custom name
                             (block-type . calendar-day))
                            ((name . "Ready to Work On")  ;; Custom name
                             (type . next-action)))))

        • Quick Reference

          Goal                        Use
          ---------------------------------------------------------
          Simple multi-section view   Multiple ‘(type . X)’ keys
          Custom block names          Explicit ‘blocks’
          Filter all blocks           Top-level filter
          Override smart default      Top-level filter
          Mix native + query blocks   Explicit ‘blocks’

   • Saving Your Custom Views

     Once you have a view you like, save it as a command:

       1. *Wrap in a function*:
               (defun my-custom-view ()
                 "Description of what this view shows."
                 (interactive)
                 (org-gtd-view-show
                  '((name . "View Name")
                    (type . delegated)
                    (when . today))))

       2. *Bind to a key* (optional):
               (global-set-key (kbd "C-c d v") 'my-custom-view)

       3. *Run with* ‘M-x my-custom-view’ or your keybinding


File: org-gtd.info,  Node: Hooks Framework Reference,  Prev: View DSL Filter Reference,  Up: Reference

1.5.6 Hooks Framework Reference
-------------------------------

   • What Are Organize Hooks?

     Hooks let you automatically capture information about tasks as you
     organize them—like tracking when tasks were created, auto-tagging
     items with "urgent" in the title, or estimating effort based on
     keywords.

     Without hooks, you'd manually add the same metadata to every task.
     With hooks, you define the pattern once and org-gtd applies it
     automatically during organization.

     For anyone who wants consistent metadata on their GTD items without
     repetitive manual work.

   • Your First Hook in 2 Minutes

     Let's add automatic creation timestamps to all tasks except trash
     and quick actions.

       1. Add this to your config:
               (defun my-track-creation-date ()
                 "Add CREATED property with current timestamp."
                 (unless (org-gtd-organize-type-member-p '(trash quick-action))
                   (org-set-property "CREATED"
                                     (format-time-string "[%Y-%m-%d %a %H:%M]"))))

               (add-to-list 'org-gtd-organize-hooks 'my-track-creation-date)

       2. Restart Emacs (or eval the code with ‘C-x C-e’)

       3. Capture something: ‘M-x org-gtd-capture’, type "Test task",
          finish capture

       4. Process it: ‘M-x org-gtd-process-inbox’, organize as "Single
          action"

       5. Look at the task: you'll see a CREATED property with today's
          timestamp

     You just automated metadata capture.  Every item you organize now
     gets timestamped automatically.

   • The org-gtd-organize-hooks Variable

     *Type*: List of functions

     *When run*: During ‘org-gtd-organize’, after you choose item type
     but before refiling

     *Purpose*: Add metadata (tags, properties, etc.)  to items as
     they're organized

     *Default value*: ‘'(org-set-tags-command)’

   • Built-in Hooks

        • ‘org-set-tags-command’

          *What it does*: Prompts for tags to add to the item

          *Use when*: You want to tag items during organization
          (default)

          *To use*:
               (setq org-gtd-organize-hooks '(org-set-tags-command))

        • ‘org-gtd-set-area-of-focus’

          *What it does*: Prompts for area of focus (from
          ‘org-gtd-areas-of-focus’) and sets CATEGORY property

          *Use when*: You use GTD Horizon 2 (areas of focus)

          *To use*:
               (setq org-gtd-organize-hooks '(org-set-tags-command
                                              org-gtd-set-area-of-focus))

          *Behavior*: Skips prompt for:
             • Project tasks (sets on project instead)
             • Trash items
             • Knowledge items
             • Quick actions

   • Writing Custom Hooks

     Custom hooks are functions that run during organization.  They can:
        • Add properties
        • Set tags
        • Modify heading text
        • Prompt for information
        • Skip certain item types

        • Basic Hook Structure

               (defun my-organize-hook ()
                 "Description of what this hook does."
                 (interactive)  ;; hooks can be interactive or not
                 ;; Your code here
                 ;; Point will be on the heading being organized
                 ;; Use org-mode functions to modify it
                 )

        • Using org-gtd-organize-type-member-p

          This helper function lets you run code only for specific item
          types.

          *Function signature*:
               (org-gtd-organize-type-member-p TYPE-LIST)

          *Arguments*:
          ‘TYPE-LIST’
               List of item type symbols to check against

          *Returns*: ‘t’ if current item matches one of the types, ‘nil’
          otherwise

          *Available types*:
          ‘'single-action’
               Single actions (do when possible)
          ‘'project-heading’
               Project headings (top-level project info)
          ‘'project-task’
               Tasks within projects
          ‘'calendar’
               Calendar items (do at a given time)
          ‘'delegated’
               Delegated items (done by someone else)
          ‘'tickler’
               Tickler items (remind me later - has a specific date)
          ‘'someday’
               Someday/maybe items (no specific timeframe)
          ‘'habit’
               Habits (recurring actions)
          ‘'knowledge’
               Reference items (stored as reference)
          ‘'quick-action’
               Quick actions (<2 min)
          ‘'trash’
               Trashed items
          ‘'everything’
               Special value: if in the list, always return t

          *Example*: Only run for single actions and project headings:
               (defun my-hook ()
                 (when (org-gtd-organize-type-member-p '(single-action project-heading))
                   ;; do something
                   ))

   • Example Custom Hooks

        • Selective Tagging with Unless

          The most common pattern is "run this hook for everything
          EXCEPT certain types".  This example prompts for tags on all
          items except trash and knowledge (reference):

               (defun my-tag-tasks ()
                 "Prompt for tags on all items except trash and knowledge."
                 (unless (org-gtd-organize-type-member-p '(trash knowledge))
                   (org-set-tags-command)))

               (setq org-gtd-organize-hooks '(my-tag-tasks))

          This replaces the default ‘org-set-tags-command’ with
          selective tagging.  The ‘unless’ pattern is cleaner than
          listing all the types you DO want: it says "skip these few,
          run for everything else."

        • Add Effort Estimation

               (defun my-add-effort ()
                 "Prompt for effort estimation when organizing single actions and projects."
                 (when (org-gtd-organize-type-member-p '(single-action project-heading))
                   (call-interactively #'org-set-effort)))

               (add-to-list 'org-gtd-organize-hooks 'my-add-effort)

        • Add Priority

               (defun my-add-priority ()
                 "Prompt for priority when organizing single actions."
                 (when (org-gtd-organize-type-member-p '(single-action))
                   (call-interactively #'org-priority)))

               (add-to-list 'org-gtd-organize-hooks 'my-add-priority)

        • Auto-Set Property Based on Keywords

               (defun my-auto-tag-urgent ()
                 "Automatically tag items with 'urgent' in their heading."
                 (when (org-gtd-organize-type-member-p '(single-action project-heading))
                   (let ((heading (org-get-heading t t t t)))
                     (when (string-match-p (regexp-quote "URGENT") heading)
                       (org-set-tags ":urgent:")))))

               (add-to-list 'org-gtd-organize-hooks 'my-auto-tag-urgent)

        • Add Custom Property

               (defun my-add-client ()
                 "Prompt for client name on work-related items."
                 (when (org-gtd-organize-type-member-p '(single-action project-heading))
                   (when (y-or-n-p "Is this for a client? ")
                     (let ((client (read-string "Client name: ")))
                       (org-set-property "CLIENT" client)))))

               (add-to-list 'org-gtd-organize-hooks 'my-add-client)

        • Integration with Org-Roam

               (defun my-link-to-roam-project ()
                 "Link GTD project to Org-Roam note."
                 (when (org-gtd-organize-type-member-p '(project-heading))
                   (when (y-or-n-p "Link to Org-Roam note? ")
                     (org-roam-node-insert))))

               (add-to-list 'org-gtd-organize-hooks 'my-link-to-roam-project)

        • Set Effort from Keywords

               (defun my-auto-set-effort ()
                 "Automatically set effort based on keywords in heading."
                 (when (org-gtd-organize-type-member-p '(single-action))
                   (let ((heading (downcase (org-get-heading t t t t))))
                     (cond
                      ((string-match-p "quick\\|call\\|email" heading)
                       (org-set-property "Effort" "0:15"))
                      ((string-match-p "meeting\\|review" heading)
                       (org-set-property "Effort" "1:00"))
                      ((string-match-p "research\\|write\\|design" heading)
                       (org-set-property "Effort" "2:00"))))))

               (add-to-list 'org-gtd-organize-hooks 'my-auto-set-effort)

   • Hook Execution Order

     Hooks run in the order they appear in ‘org-gtd-organize-hooks’.

     *Example*: Set area first, then tags:
          (setq org-gtd-organize-hooks
                '(org-gtd-set-area-of-focus  ;; runs first
                  org-set-tags-command))      ;; runs second

     This order matters if one hook depends on another's results.

   • Best Practices

       1. *Use type checking*: Always use
          ‘org-gtd-organize-type-member-p’ to run hooks only for
          relevant item types

       2. *Keep hooks focused*: Each hook should do one thing well

       3. *Make hooks optional*: Use ‘y-or-n-p’ for optional metadata:
               (when (y-or-n-p "Add custom property? ")
                 (org-set-property "PROP" value))

       4. *Test interactively*: Make hooks interactive for testing:
               (defun my-hook ()
                 (interactive)  ;; can test with M-x my-hook
                 ...)

       5. *Handle errors gracefully*: Wrap risky code in condition-case:
               (condition-case err
                   (my-risky-operation)
                 (error (message "Hook failed: %s" err)))

       6. *Document your hooks*: Add docstrings explaining what each
          hook does

   • Complete Example: Comprehensive Hook Setup

          ;; Custom hooks for org-gtd
          (defun my-add-effort ()
            "Prompt for effort on single actions and projects."
            (when (org-gtd-organize-type-member-p '(single-action project-heading))
              (call-interactively #'org-set-effort)))

          (defun my-add-priority ()
            "Prompt for priority on single actions."
            (when (org-gtd-organize-type-member-p '(single-action))
              (call-interactively #'org-priority)))

          (defun my-auto-tag-contexts ()
            "Automatically suggest context tags based on heading keywords."
            (when (org-gtd-organize-type-member-p '(single-action))
              (let* ((heading (downcase (org-get-heading t t t t)))
                     (suggested-tags '()))
                (when (string-match-p "\\(phone\\|call\\)" heading)
                  (push "@phone" suggested-tags))
                (when (string-match-p "\\(computer\\|code\\|write\\)" heading)
                  (push "@computer" suggested-tags))
                (when (string-match-p "\\(store\\|buy\\|shop\\)" heading)
                  (push "@errands" suggested-tags))
                (when suggested-tags
                  (message "Suggested contexts: %s" (string-join suggested-tags ", "))))))

          (defun my-track-creation-date ()
            "Add CREATED property with current timestamp."
            (unless (org-gtd-organize-type-member-p '(trash quick-action))
              (org-set-property "CREATED"
                                (format-time-string "[%Y-%m-%d %a %H:%M]"))))

          ;; Install hooks
          (setq org-gtd-organize-hooks
                '(org-gtd-set-area-of-focus  ;; set area first
                  org-set-tags-command        ;; then tags
                  my-auto-tag-contexts        ;; suggest context tags
                  my-add-effort               ;; estimate effort
                  my-add-priority             ;; set priority if needed
                  my-track-creation-date))    ;; track when created

     This creates a comprehensive metadata capture workflow during
     organization.


File: org-gtd.info,  Node: Extending org-gtd,  Next: Troubleshooting,  Prev: Reference,  Up: Summary

1.6 Extending org-gtd
=====================

org-gtd provides public API functions for building custom functionality.

* Menu:

* Project Traversal Functions::


File: org-gtd.info,  Node: Project Traversal Functions,  Up: Extending org-gtd

1.6.1 Project Traversal Functions
---------------------------------

   • ‘org-gtd-project-map-tasks’

     Apply a function to each task in a project's dependency graph.

          (org-gtd-project-map-tasks FN PROJECT-MARKER)

     ‘FN’
          Function called with point at each task heading
     ‘PROJECT-MARKER’
          Marker to the project heading
     Returns
          List of non-nil results from FN

     *Example*: Collect all task headlines in a project:
          (org-gtd-project-map-tasks
           (lambda () (org-get-heading t t t t))
           project-marker)

     *Example*: Sum effort estimates:
          (apply #'+ (org-gtd-project-map-tasks
                      (lambda ()
                        (or (org-duration-to-minutes
                             (org-entry-get nil "Effort")) 0))
                      project-marker))

   • ‘org-gtd-projects-map’

     Apply a function to each project in your GTD system.

          (org-gtd-projects-map FN)

     ‘FN’
          Function called with point at each project heading
     Returns
          Alist of ‘(marker . result)’ for non-nil results

     *Example*: Find projects missing effort estimates:
          (org-gtd-projects-map
           (lambda ()
             (unless (org-entry-get nil "Effort")
               (org-get-heading t t t t))))

     *Example*: Get clock totals for all projects:
          (org-gtd-projects-map
           (lambda ()
             (cons (org-get-heading t t t t)
                   (org-clock-sum-current-item))))


File: org-gtd.info,  Node: Troubleshooting,  Prev: Extending org-gtd,  Up: Summary

1.7 Troubleshooting
===================

This section covers common problems and their solutions.  For complete
command documentation, see *note Commands Reference::.

* Menu:

* Finding lost tasks::
* Projects without a NEXT item::
* I can't create a project when clarifying an inbox item!::
* Configuration problems::
* Tasks still showing after tickler'ing or someday'ing project::
* Still stuck?::


File: org-gtd.info,  Node: Finding lost tasks,  Next: Projects without a NEXT item,  Up: Troubleshooting

1.7.1 Finding lost tasks
------------------------

Sometimes items get stuck or fall through the cracks.  org-gtd provides
several commands to find problematic items:

‘org-gtd-reflect-stuck-calendar-items’
     Calendar items with invalid or missing timestamps
‘org-gtd-reflect-stuck-tickler-items’
     Tickler items with invalid or missing review dates
‘org-gtd-reflect-stuck-habit-items’
     Habits with incorrect configuration
‘org-gtd-reflect-stuck-delegated-items’
     Delegated items missing delegate or date information
‘org-gtd-reflect-stuck-single-action-items’
     Single actions that aren't marked as NEXT
‘org-gtd-reflect-stuck-projects’
     Projects that have tasks but no NEXT actions
‘org-gtd-reflect-missed-items’
     Items that should have been processed but weren't

   See *note Commands Reference:: for detailed documentation of these
commands.


File: org-gtd.info,  Node: Projects without a NEXT item,  Next: I can't create a project when clarifying an inbox item!,  Prev: Finding lost tasks,  Up: Troubleshooting

1.7.2 Projects without a NEXT item
----------------------------------

If a project has active tasks but none are marked NEXT, this usually
indicates:
  1. Missing dependency configuration (no ‘ORG_GTD_FIRST_TASKS’
     property)
  2. org-edna is not enabled
  3. Dependency properties need recalculation
  4. Task states are inconsistent after external edits (mobile apps,
     sync conflicts)

   *Solution for one project*: Put the point on the project heading and
run ‘M-x org-gtd-projects-fix-todo-keywords-for-project-at-point’.

   *Solution for all projects*: Run ‘M-x
org-gtd-projects-fix-all-todo-keywords’ to fix all projects at once.
This is especially useful after:
   • Editing tasks on mobile apps or web interfaces
   • Resolving sync conflicts
   • Bulk manual edits outside org-gtd
   • Migrating or importing data

   *Note*: Make sure org-edna is enabled: ‘(org-edna-mode 1)’ in your
init file.  See *note Configuring:: for setup instructions.

   See also: *note Working with Projects (Advanced):: for complete
project troubleshooting guide.


File: org-gtd.info,  Node: I can't create a project when clarifying an inbox item!,  Next: Configuration problems,  Prev: Projects without a NEXT item,  Up: Troubleshooting

1.7.3 I can't create a project when clarifying an inbox item!
-------------------------------------------------------------

When organizing an item as a project, org-gtd expects a specific
structure:

     * Project heading
     ** First task
     ** Second task
     ** Third task

   *Common issues*:
   • Top-level heading must be a single asterisk ‘*’
   • Tasks must be second-level headings ‘**’
   • Must have at least one task under the project heading

   See *note data shape requirements:: for complete details.

   If this doesn't solve your problem, please open an issue at
<https://github.com/Trevoke/org-gtd.el/issues> with:
  1. The exact structure of your item in the clarify buffer
  2. What happens when you try to organize it
  3. Any error messages


File: org-gtd.info,  Node: Configuration problems,  Next: Tasks still showing after tickler'ing or someday'ing project,  Prev: I can't create a project when clarifying an inbox item!,  Up: Troubleshooting

1.7.4 Configuration problems
----------------------------

   • Keywords not working

     If TODO keywords aren't changing correctly:

       1. *Check ‘org-todo-keywords’ includes all GTD keywords in one
          sequence*:
               (setq org-todo-keywords
                     '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CNCL")))

       2. *Check ‘org-gtd-keyword-mapping’ maps to those keywords*:
               (setq org-gtd-keyword-mapping
                     '((todo . "TODO")
                       (next . "NEXT")
                       (wait . "WAIT")
                       (done . "DONE")
                       (canceled . "CNCL")))

       3. *Remove any ‘#+TODO:’ lines from GTD org files*

     See *note Configuring:: for complete setup instructions.

   • Items not showing in engage view

     If items aren't appearing in ‘org-gtd-engage’:

       1. *Check org-agenda-files includes org-gtd-directory*:
               ;; Must be set after org-gtd loads
               (with-eval-after-load 'org-gtd
                 (setq org-agenda-files (list org-gtd-directory)))
          For ‘use-package’, put this in the ‘:config’ section.

       2. *Check item has correct properties*:
             • Single actions should have ‘ORG_GTD: Actions’ and TODO
               keyword NEXT
             • Project tasks should have ‘ORG_GTD: Actions’ and be part
               of a project

       3. *Verify org-edna is enabled*:
               (org-edna-mode 1)

     See *note Configuration Variables Reference:: for all configuration
     options.


File: org-gtd.info,  Node: Tasks still showing after tickler'ing or someday'ing project,  Next: Still stuck?,  Prev: Configuration problems,  Up: Troubleshooting

1.7.5 Tasks still showing after tickler'ing or someday'ing project
------------------------------------------------------------------

*Symptom*: Moved a project to tickler or someday/maybe, but some tasks
still appear in engage view.

   *Diagnosis*:
   • Multi-project tasks (tasks shared between projects) use "last
     active project" logic
   • If task belongs to Project A and Project B, and you only
     tickler/someday Project A, the task stays visible because Project B
     is still active
   • This is intentional—the task is genuinely needed by an active
     project

   *Solution*:
   • Check task's ‘ORG_GTD_PROJECT_IDS’ property to see which projects
     it belongs to
   • Each project that's still active (‘ORG_GTD: Projects’, not
     done/cancelled) keeps the task visible
   • Incubate all active projects the task belongs to if you want it
     fully hidden

   *How it works*:
  1. When incubating Project X, org-gtd checks each task's other
     projects
  2. If any other project is still active, the task stays active
     (correct behavior)
  3. If Project X is the task's _last_ active project, the task gets
     incubated


File: org-gtd.info,  Node: Still stuck?,  Prev: Tasks still showing after tickler'ing or someday'ing project,  Up: Troubleshooting

1.7.6 Still stuck?
------------------

If you're still having problems:

  1. Check *note Reference:: for complete documentation
  2. Search existing issues:
     <https://github.com/Trevoke/org-gtd.el/issues>
  3. Ask on Discord: <https://discord.gg/2kAK6TfqJq>
  4. Open a new issue with:
        • Your org-gtd configuration
        • Steps to reproduce the problem
        • Expected vs actual behavior
        • Any error messages


Tag Table:
Node: Top736
Node: Summary3352
Node: What's new in 407382
Node: Flexible project dependencies (the big one!)8126
Node: Simplified keyword configuration9246
Node: Data-driven configuration10270
Node: Declarative view language10859
Node: Better project modification11460
Node: Updated terminology Review → Reflect11939
Node: Updated terminology Incubate → Tickler + Someday/Maybe12534
Node: Enhanced reflect capabilities14084
Node: Simplified configuration14560
Node: Per-type refile prompting15042
Node: Capture timestamps15831
Node: What you need to do16524
Node: Previous versions17203
Node: Setting up Org GTD17437
Node: Upgrading17841
Ref: 400 <- 3xx18095
Ref: Required Configuration changes18390
Ref: Required Configure org-agenda-files20202
Ref: Required Data migration20967
Ref: Required Acknowledge the upgrade23408
Ref: Why these changes?24814
Ref: org-gtd-mode has a new purpose25569
Ref: org-agenda-property has been vendored26134
Node: Installing27330
Ref: use-package27597
Ref: Manually27726
Node: Configuring28020
Ref: Basic setup28150
Ref: Complete Configuration Examples28993
Ref: Example 1 Vanilla Emacs (Minimal Configuration)29203
Ref: Example 2 Doom Emacs Configuration32061
Ref: Example 3 Spacemacs Configuration34319
Ref: What These Configurations Do36555
Ref: Testing Your Configuration38121
Ref: Common Configuration Problems39464
Ref: Working with Your Existing Org Setup43282
Ref: Understanding Keybindings45375
Ref: Global Keybindings45511
Ref: Clarify Map Keybindings46156
Ref: Required configuration of sub-packages47397
Ref: Configuring org-edna47449
Ref: Adding org-gtd files to your agenda47778
Ref: configuration options for org-gtd48590
Ref: I don't care just let me start using it48637
Ref: Tell me all the levers I can pull49274
Ref: Required keyword configuration49452
Ref: Optional configuration52288
Ref: Recommended key bindings57785
Ref: Command Center58435
Ref: Sample Doom Emacs Config59327
Node: Getting Started with Org GTD60756
Node: Quick Start Reference61220
Node: Tutorial Your First Project61762
Ref: What You'll Learn62219
Ref: The Project62524
Ref: Step 1 Capture the Project62831
Ref: Step 2 Process the Inbox63321
Ref: Step 3 Organize as a Project63740
Ref: Step 4 View in Engage64321
Ref: Step 5 Complete the First Task64840
Ref: Step 6 Refresh and See the Change65190
Ref: What Just Happened?65576
Ref: Continue the Project66563
Ref: Key Takeaways67006
Ref: What's Next?67533
Node: Tutorial Creating Your First Custom View68214
Ref: What You'll Learn (1)68735
Ref: Why This View?68967
Ref: Understanding the View DSL69356
Ref: Creating the View Function69885
Ref: Using Your View70362
Ref: Binding to a Key70508
Ref: What You'll See71127
Ref: Experiment Modify the View71543
Ref: Available Filters72534
Ref: Key Takeaways (1)74732
Ref: What's Next? (1)75197
Node: Tutorial Quick Wins and Focus Work Views75696
Ref: Why This Matters76141
Ref: Your First Quick Wins View (30 seconds)76620
Ref: The Effort Filter Explained77146
Ref: Building a Focus Work View77845
Ref: The Priority Filter Explained78386
Ref: Finding Tasks to Triage79056
Ref: Bonus The Clocked Filter79659
Ref: Putting It All Together80368
Ref: Key Takeaways (2)81539
Ref: Where to Go From Here81960
Node: Using Org GTD83137
Node: Your Daily Workflow83765
Ref: Quick command reference84625
Node: The GTD Flow in Depth86159
Ref: Adding things to the inbox86413
Ref: Processing the inbox87742
Ref: Clarifying each item88466
Ref: How to start clarifying88835
Ref: data shape requirements89388
Ref: Options and commands related to clarification90015
Ref: Duplicating items during clarification92463
Ref: Your first duplicate in 30 seconds92954
Ref: Understanding the workflow93395
Ref: The queue window94202
Ref: Two ways to duplicate94759
Ref: What happens if you cancel?95450
Ref: Nested duplicates96123
Ref: Data safety96360
Ref: Configuration96845
Ref: Organizing an item into the system97239
Ref: Refiling to the appropriate area98027
Ref: Understanding Refiling in V498078
Ref: Refile Target System98529
Ref: Controlling Refile Prompts by Item Type99735
Ref: Creating New Refile Targets102240
Ref: Multiple Types Per Heading103033
Ref: Using Your Own Refile Targets103756
Ref: Migration from V3104499
Ref: Engaging with your GTD items105173
Ref: Quick Task Actions from the Agenda105709
Ref: First Contact Why This Feature?105762
Ref: Black Triangle Your First Quick Action106498
Ref: Understanding the Actions107337
Ref: State Changes107496
Ref: Time Adjustments (Conditional)108046
Ref: Clocking109136
Ref: Metadata109349
Ref: Clarify109902
Ref: Command Reference110253
Ref: Suggested Keybinding111593
Node: Understanding GTD Item Types111963
Ref: Single Action [S]112480
Ref: Project [P]113055
Ref: Add to existing project [A]113967
Ref: Calendar [C]114732
Ref: Delegate [D]115491
Ref: Quick Action [Q]116749
Ref: Tickler [I]117291
Ref: Someday/Maybe [y]118826
Ref: Habit [H]121619
Ref: Knowledge [K]122233
Ref: Trash [T]122897
Ref: Working with the GTD Horizons123671
Ref: Areas of focus124295
Ref: Longer-term horizons125696
Node: Working with Projects (Advanced)127496
Ref: Quick Navigation127989
Ref: First Contact Why Visual Project Management?129208
Ref: Black Triangle Your First Project Graph View130043
Ref: Step 1 Find a project130144
Ref: Step 2 Open the graph view130342
Ref: Step 3 Explore130525
Ref: Understanding Project Dependencies131149
Ref: The Dependency Graph (DAG)131291
Ref: What You See in Graph View131898
Ref: Sequential vs Parallel vs Mixed132625
Ref: Tutorial Parallel Tasks with Graph View133628
Ref: The Scenario133750
Ref: Step 1 Capture and Organize134206
Ref: Step 2 Open Graph View134609
Ref: Step 3 Modify Dependencies to Create Parallel Tasks135255
Ref: What Graph View CAN Do135931
Ref: Building Our Parallel Structure136584
Ref: The Diamond Pattern in Action137462
Ref: Alternative Approach Add Blockers138012
Ref: Tutorial Complex Dependencies with Graph View138607
Ref: The Scenario (1)138667
Ref: The Dependency Graph139293
Ref: Building with Graph View139886
Ref: Creating the Convergence Point140385
Ref: Building the Rest140866
Ref: The Complete Graph141416
Ref: Key Patterns This Example Shows142097
Ref: Common Dependency Patterns (Visual Reference)142558
Ref: Sequential Chain (A → B → C)142679
Ref: Parallel Independent (A B C all start together)143149
Ref: Fan-out (A → B A → C A → D)143538
Ref: Fan-in / Convergence (A → C B → C)144047
Ref: Diamond (A → B → D A → C → D)144506
Ref: Graph View Command Reference145174
Ref: Opening Graph View145374
Ref: Tier 1 Single-Key Commands (Always Available)145672
Ref: Tier 2 Prefixed Commands149022
Ref: Visual Indicators150575
Ref: Operations Not Available in Graph View150881
Ref: Text-Based Alternatives151704
Ref: Graph Rendering Modes153039
Ref: SVG Mode (Default)153241
Ref: ASCII Mode153602
Ref: Toggling Modes153987
Ref: Troubleshooting ASCII Rendering154113
Ref: Complete Keyboard Reference154476
Ref: Tier 1 Single Keys154600
Ref: Tier 2 Task Operations (t prefix)155545
Ref: Tier 2 Project and View Operations155922
Ref: Auto-Refresh on File Changes156373
Ref: Technical Details156868
Ref: Graph Data Structure156899
Ref: Layout Algorithm157299
Ref: Properties Used157655
Ref: Undo/Redo Support158601
Ref: Practical Tips for Project Management158980
Ref: When to Use Graph View159031
Ref: When to Use Sequential (Default)159438
Ref: When to Create Parallel Structures159854
Ref: Managing Complexity160222
Ref: Growing Projects Over Time160666
Ref: Canceling Projects161105
Ref: Exporting Project Graphs162121
Ref: First Contact What is Graph Export?162159
Ref: Tutorial Export Your First Graph162901
Ref: Progressive Learning Choosing Export Formats163463
Ref: When Exports Differ from Display165304
Ref: Reference Export Commands165918
Ref: Troubleshooting Exports166608
Ref: Troubleshooting Projects with Graph View167396
Ref: Project is Stuck (has TODO tasks but no NEXT)167450
Ref: Task Should Be NEXT But Shows as TODO168384
Ref: Too Many Tasks Are NEXT169034
Ref: Graph Won't Open169534
Ref: Graph Shows No Tasks169934
Ref: Task Shows Wrong State (NEXT vs TODO)170369
Ref: Can't Modify Dependencies170872
Ref: See Also171324
Ref: Tickler Projects Pausing Work You're Not Ready For171821
Ref: First Contact Why Tickler Projects?171886
Ref: Black Triangle Tickler Your First Project in 30 Seconds172954
Ref: Understanding Tickler What Actually Happens173867
Ref: Tutorial Managing Seasonal Projects176117
Ref: Common Patterns and Scenarios178581
Ref: Advanced External Dependencies and Warnings180862
Ref: Technical Details How Tickler Works Under the Hood183178
Ref: Troubleshooting Tickler187039
Ref: See Also (1)190326
Ref: Project Progress Cookies See Your Progress at a Glance190956
Ref: First Contact What Are Progress Cookies?191025
Ref: Black Triangle See Progress in 30 Seconds191586
Ref: Tutorial Watch Cookies Update Automatically192073
Ref: Understanding How Cookies Work192887
Ref: Configuring Cookie Position193959
Ref: Common Scenarios194793
Ref: Technical Reference195630
Ref: Cleaning up / archiving completed work196559
Ref: Commands you can call on org-agenda197253
Ref: Defining your own agenda views198051
Ref: Adding your own hooks when organizing198751
Node: Automating through emacs200021
Node: Reference201324
Node: Configuration Variables Reference202770
Ref: Required Configuration203077
Ref: org-todo-keywords (org-mode variable)203113
Ref: org-gtd-keyword-mapping204200
Ref: Directory and File Configuration205364
Ref: org-gtd-directory205410
Ref: org-gtd-additional-inbox-files206509
Ref: org-gtd-horizons-file207482
Ref: Capture Configuration207915
Ref: org-gtd-capture-templates207950
Ref: Organize and Process Configuration209230
Ref: org-gtd-organize-hooks209278
Ref: org-gtd-save-after-organize210822
Ref: org-gtd-refile-to-any-target (deprecated)211173
Ref: org-gtd-refile-prompt-for-types212475
Ref: Mode-Line Configuration213910
Ref: org-gtd-mode-update-interval213947
Ref: org-gtd-mode-lighter-display214838
Ref: Clarification Configuration215412
Ref: org-gtd-clarify-show-horizons215453
Ref: org-gtd-clarify-show-organize-help216217
Ref: org-gtd-clarify-display-helper-buffer217341
Ref: org-gtd-clarify-project-templates217990
Ref: org-gtd-clarify-duplicate-queue-position219191
Ref: Areas of Focus Configuration220024
Ref: org-gtd-areas-of-focus220066
Ref: View Prefix Configuration220718
Ref: org-gtd-prefix-width220757
Ref: org-gtd-agenda-truncate-ellipsis221760
Ref: Archive Configuration222541
Ref: org-gtd-archive-location222576
Ref: Missed Engagements Review Configuration224219
Ref: org-gtd-reflect-missed-custom-views224272
Ref: Advanced Item Configuration225647
Ref: org-gtd-user-types225688
Ref: Agenda Display Configuration229077
Ref: org-gtd-agenda-property-list229357
Ref: org-gtd-agenda-property-position229907
Ref: org-gtd-agenda-property-column230544
Ref: org-gtd-agenda-property-separator230995
Ref: Graph View Configuration231355
Ref: org-gtd-graph-render-mode231464
Ref: org-gtd-graph-ui-split-ratio232216
Ref: org-gtd-graph-sibling-mode232989
Ref: Projects Configuration235437
Ref: org-gtd-project-progress-cookie-position235473
Ref: Obsolete Variables (Do Not Use)237653
Ref: org-gtd-todo-keyword (obsolete)237799
Ref: org-gtd-next-keyword (obsolete)237927
Ref: org-gtd-wait-keyword (obsolete)238055
Ref: org-gtd-canceled-keyword (obsolete)238183
Node: Commands Reference238307
Ref: Core GTD Workflow Commands238622
Ref: org-gtd-command-center238662
Ref: org-gtd-capture239955
Ref: org-gtd-process-inbox240599
Ref: org-gtd-organize241444
Ref: org-gtd-engage242415
Ref: org-gtd-show-all-next243221
Ref: Reflect Commands243614
Ref: org-gtd-reflect-stuck-projects243644
Ref: org-gtd-reflect-area-of-focus244212
Ref: org-gtd-reflect-completed-items244823
Ref: org-gtd-reflect-completed-projects245373
Ref: org-gtd-reflect-missed-items245622
Ref: Stuck Item Review Commands245911
Ref: org-gtd-reflect-stuck-calendar-items246035
Ref: org-gtd-reflect-stuck-tickler-items246159
Ref: org-gtd-reflect-stuck-habit-items246283
Ref: org-gtd-reflect-stuck-delegated-items246395
Ref: org-gtd-reflect-stuck-single-action-items246538
Ref: Reviewing Someday/Maybe Items246654
Ref: Your First Review in 60 Seconds247278
Ref: Understanding the Review Workflow247755
Ref: Tutorial Weekly Someday Review248469
Ref: Organizing Your Someday Items (Optional)249378
Ref: Common Patterns250169
Ref: Command Reference (1)250926
Ref: org-gtd-reflect-someday-review251385
Ref: Reflect Commands (Missed Engagements)252400
Ref: What Are Missed Engagements?252451
Ref: Your First Review in 30 Seconds253268
Ref: Understanding the Review Workflow (1)253735
Ref: Tutorial Daily Review Workflow254483
Ref: Common Patterns (1)255316
Ref: Command Reference (2)255828
Ref: Backward Compatibility Note256588
Ref: Reflect Commands (Upcoming Delegated)257280
Ref: What Are Upcoming Delegated Check-ins?257331
Ref: Your First Review in 30 Seconds (1)258159
Ref: Understanding Proactive Delegation Management258667
Ref: Tutorial Weekly Planning Workflow259326
Ref: Common Patterns (2)260460
Ref: Understanding What You See261241
Ref: Comparison Missed vs Upcoming262027
Ref: Command Reference (3)262537
Ref: Custom View Commands262962
Ref: org-gtd-view-show262996
Ref: Clarification Commands273309
Ref: org-gtd-clarify-item273345
Ref: org-gtd-clarify-agenda-item273831
Ref: org-gtd-clarify-toggle-horizons-window274124
Ref: org-gtd-clarify-toggle-organize-help274490
Ref: org-gtd-clarify-project-insert-template275083
Ref: org-gtd-clarify-duplicate275426
Ref: org-gtd-clarify-duplicate-exact276278
Ref: org-gtd-clarify-stop276771
Ref: Updating Items Without Refiling277162
Ref: Archive Commands282243
Ref: org-gtd-archive-completed-items282273
Ref: Agenda-Specific Commands282798
Ref: org-gtd-delegate-agenda-item282900
Ref: org-gtd-project-cancel-from-agenda283263
Ref: Timestamp Commands (DWIM)283705
Ref: org-gtd-set-timestamp283861
Ref: Project Task Commands (DWIM)284548
Ref: org-gtd-project-add-successor284749
Ref: org-gtd-project-add-blocker285228
Ref: org-gtd-project-add-root-task285720
Ref: org-gtd-project-remove-task286118
Ref: org-gtd-project-trash-task286530
Ref: org-gtd-project-change-state286902
Ref: Project Management Commands287190
Ref: org-gtd-projects-fix-todo-keywords-for-project-at-point287231
Ref: org-gtd-projects-fix-all-todo-keywords287881
Ref: org-gtd-project-update-all-cookies290923
Ref: org-gtd-tickler292549
Ref: org-gtd-someday294391
Ref: org-gtd-reactivate296098
Ref: Task Dependency Commands298215
Ref: org-gtd-task-add-blockers298993
Ref: org-gtd-task-remove-blockers299814
Ref: org-gtd-task-add-dependent300120
Ref: org-gtd-task-add-dependents300853
Ref: org-gtd-task-clear-relationships301125
Ref: org-gtd-task-show-relationships301498
Ref: org-gtd-validate-project-dependencies301888
Ref: org-gtd-remove-task-from-project302362
Ref: Area of Focus Commands302736
Ref: org-gtd-area-of-focus-set-on-item-at-point302772
Ref: org-gtd-area-of-focus-set-on-agenda-item303179
Ref: Programmatic Creation Commands303554
Ref: org-gtd-habit-create303703
Ref: org-gtd-calendar-create303964
Ref: org-gtd-delegate-create304228
Ref: org-gtd-tickler-create304952
Ref: org-gtd-someday-create305245
Ref: org-gtd-single-action-create305494
Ref: Utility Commands305715
Ref: org-gtd-setup-keywords-wizard305745
Ref: org-gtd-inbox-path306097
Ref: Migration and Upgrade Commands306511
Ref: org-gtd-upgrade-v3-to-v4306555
Ref: Mode-Line Integration307167
Ref: org-gtd-mode307202
Ref: org-gtd-inbox-count307945
Ref: Obsolete Commands308229
Ref: org-gtd-delegate-item-at-point (removed in 40)308260
Node: Properties Reference (Internal Implementation)309122
Ref: Core GTD Properties310011
Ref: ORG_GTD310044
Ref: ORG_GTD_REFILE311122
Ref: Project Properties313473
Ref: ORG_GTD_FIRST_TASKS313505
Ref: Task Dependency Properties314444
Ref: ORG_GTD_DEPENDS_ON314484
Ref: ORG_GTD_BLOCKS316402
Ref: ORG_GTD_PROJECT_IDS317239
Ref: Calendar and Time Properties317589
Ref: ORG_GTD_TIMESTAMP317631
Ref: Delegation Properties318573
Ref: DELEGATED_TO318608
Ref: Habit Properties319560
Ref: STYLE319590
Ref: Area of Focus Properties320061
Ref: CATEGORY320099
Ref: Standard Org Properties Used by org-gtd320970
Ref: ID321023
Ref: keyword321300
Ref: SCHEDULED (org-mode standard)321955
Ref: DEADLINE (org-mode standard)322230
Node: Troubleshooting Projects322473
Ref: Fixing Broken Dependencies322994
Ref: When Manual Property Editing is Needed324281
Ref: Common Problems and Solutions326077
Ref: Project Shows No NEXT Tasks (Stuck Project)326120
Ref: Too Many NEXT Tasks326954
Ref: Task Won't Advance to NEXT327428
Ref: Task States Inconsistent After External Edits328130
Node: View DSL Filter Reference329338
Ref: Your First Custom View in 60 Seconds329855
Ref: Understanding View Specs330415
Ref: Combining Filters330999
Ref: Multi-Block Views331434
Ref: Common Patterns (3)332057
Ref: Weekly Review View332086
Ref: Morning Planning View332656
Ref: Area of Focus View333347
Ref: Filter Reference333987
Ref: View Structure334127
Ref: Multi-Block Views (1)334472
Ref: Block Types335210
Ref: Native Blocks (Escape Hatch)335731
Ref: When You'll Need This336191
Ref: Your First Native Block336867
Ref: Adding Custom Sorting338036
Ref: Mixing DSL and Native338898
Ref: Native Block Types339850
Ref: Quick Reference340483
Ref: Type Filters341106
Ref: (type delegated)341163
Ref: (type calendar)341448
Ref: (type project)341703
Ref: (type active-project)341944
Ref: (type completed-project)342223
Ref: (type stuck-project)342529
Ref: (type tickler)342849
Ref: (type someday)343136
Ref: (type habit)343430
Ref: (type next-action)343652
Ref: (type tickler-project)343969
Ref: (type incubated-project)344426
Ref: (type stuck-delegated)344909
Ref: (type stuck-calendar)345280
Ref: (type stuck-tickler)345563
Ref: (type stuck-habit)345846
Ref: Time-based Filters346104
Ref: Semantic Time (when VALUE)346196
Ref: Deadline (deadline VALUE)347157
Ref: Scheduled (scheduled VALUE)347402
Ref: Keyword Filters347657
Ref: (todo ("KEYWORD1" "KEYWORD2"))347974
Ref: (done VALUE)348398
Ref: Area of Focus Filters349683
Ref: (area-of-focus "AREA")349745
Ref: Tag Filters350162
Ref: (tags ("TAG1" "TAG2"))350213
Ref: (tags-match "PATTERN")350536
Ref: Priority Effort and Clocked Filters351071
Ref: (priority VALUE)351213
Ref: (effort SPEC)352532
Ref: (clocked SPEC)353737
Ref: (last-clocked-out SPEC)354855
Ref: Property Filters356156
Ref: (property (("PROP" "VALUE")))356228
Ref: Structural Filters356547
Ref: (level N)356618
Ref: Special Filters357018
Ref: (not-habit t)357047
Ref: (invalid-timestamp t)357326
Ref: View Configuration Options357672
Ref: (block-type TYPE)357767
Ref: (blocks BLOCK-LIST)358631
Ref: Prefix DSL Customizing the Task Prefix Column359307
Ref: Your First Prefix in 60 Seconds359806
Ref: (prefix (ELEMENT ))360455
Ref: (prefix-width N)361787
Ref: Prefix Inheritance in Multi-Block Views362431
Ref: Low-Level (prefix-format FORMAT-STRING)363614
Ref: (view-type agenda)364216
Ref: (agenda-span N)364553
Ref: Simplified Multi-Block Views364719
Ref: The Problem Verbose Block Definitions365004
Ref: The Solution Implicit Blocks365911
Ref: Try It Now366602
Ref: Smart Type Defaults367264
Ref: Top-Level Inheritance368212
Ref: The Four-Tier Precedence Model368596
Ref: When to Use Explicit Blocks369760
Ref: Quick Reference (1)370438
Ref: Saving Your Custom Views370872
Node: Hooks Framework Reference371440
Ref: What Are Organize Hooks?371618
Ref: Your First Hook in 2 Minutes372165
Ref: The org-gtd-organize-hooks Variable373192
Ref: Built-in Hooks373513
Ref: org-set-tags-command373541
Ref: org-gtd-set-area-of-focus373819
Ref: Writing Custom Hooks374400
Ref: Basic Hook Structure374659
Ref: Using org-gtd-organize-type-member-p375033
Ref: Example Custom Hooks376678
Ref: Selective Tagging with Unless376712
Ref: Add Effort Estimation377494
Ref: Add Priority377879
Ref: Auto-Set Property Based on Keywords378219
Ref: Add Custom Property378742
Ref: Integration with Org-Roam379228
Ref: Set Effort from Keywords379634
Ref: Hook Execution Order380428
Ref: Best Practices380801
Ref: Complete Example Comprehensive Hook Setup381698
Node: Extending org-gtd383877
Node: Project Traversal Functions384142
Ref: org-gtd-project-map-tasks384300
Ref: org-gtd-projects-map385106
Node: Troubleshooting385789
Node: Finding lost tasks386278
Node: Projects without a NEXT item387287
Node: I can't create a project when clarifying an inbox item!388547
Node: Configuration problems389509
Ref: Keywords not working389783
Ref: Items not showing in engage view390517
Node: Tasks still showing after tickler'ing or someday'ing project391327
Node: Still stuck?392670

End Tag Table


Local Variables:
coding: utf-8
Info-documentlanguage: en
End:
