Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Process Overview

Our fundamental unit of measurement is lists of actions.

Therefore, the entire system can be thought of as no more or less than a set of interconnected lists of actions.

This process covers the workflow to manage the state of said actions as they move through the system.

This process is built around the human-editable Actions File Format. Implementations may project those facts into the canonical Action JSON Schema, RDF, tables, or other presentations without making those projections a second workspace authority.

The process can be adapted to different implementation methods and delivery backends.

Capture

Like GTD, we can always start our actions in the “Inbox” whether that be a file, a binary format, or a physical tray a core piece of the system is the idea of an inbox where all the new stuff is aggregated.

Normally, it is assumed that people will be writing to the root charter’s next.actions file which you can read more about in the Workspace specification.

Remember, we arent putting all the details in yet, just get it out of your head and into the inbox.

5 Minute Rule

The 5 minute rule answers that annoying question “how do i know when something is too small for the inbox?”. the answer is “when it takes you longer to write it down than to do it”.

For most people, this can be ~5 minutes or less. so, if you know an action will take less than 5 minutes, and you CAN do it right now, just do it.

It seems small, but this core insight is one of the most powerful ways to get seemingly small things done that can have major impact while making the process of maintaining the list easier.

List Size

The 5 minute rule has a more subtle benefit. Its important to understand that as your action list grows, so does the sophistication needed to manage it.

Therefore, discipline is required to keep the list manageable and the 5 minute rule is a key part of that.

Clarify

Its also where the really hard work happens of deciding what ACTIONS need to be done to get to an intended outcome.

In particular, we want to have a viscious focus on writing down the next physical action that needs to be done to move something forward.

In many ways, this is the most important, and most difficult part of the process but is also the part that makes the system save more work than it costs as this allows us to do our thinking ahead-of-time such that by the time we get to doing the work, we already know exactly what to do and just have a list of next actions to follow.

This is also where we link our actions to the proper research material, next-step links and really CLARIFYING what is needed to move forward

We should also figure out what actions are indepedent and dependent, making sure to mark actions with dependendent actions as we work through the list

Another important consideration is the addition of tags as context for these actions so that we can filter down based on the context this action must be done within

Timeframes and Dates

While this system supports explicit time-blocking, scheduling hard chunks on the calendar is often overwhelming and requires more knowledge of the future than is available. Undated Actions should therefore remain normal and rely on priority and context when no calendar commitment demands attention.

When timing constraints are real, they live in the Action’s due window (:): a deadline, optionally with a lower bound before which it cannot be done. The do date (@) is separate: when we intend to work it, which bounds nothing. An Action hierarchy composes windows by intersection: the effective window opens at the latest lower bound on the Action or any ancestor, and closes at the earliest deadline. The complete field and coherence semantics are defined in Actions File Format.

These effective values are query-time derivations. They do not justify writing inherited dates into descendants or manufacturing calendar commitments merely to make the projection easier to compute.

Organize

As we move through the inbox, we either complete actions, or move them to the appropriate action list

Like in other systems, its not about finishing everything necessarily its about putting them in the right place whether that be in the main workspace, a project folder, or even a someday/maybe list.

This is also usually where we start setting due/do dates on the calendar (yes, we have both).

Recurring work is defined as Habits in `.habits.actions`; `.ics` is the editable calendar projection, and deterministic occurrences live in ordinary `.actions`.

This is also where priorities can be assigned on the RFC 5545-aligned 1-9 scale (1 highest, 9 lowest); urgency and importance remain separate planning judgments rather than encoded quadrants.

On IDs

By the time we move the actions out of the inbox, it is recommended that each action is given a unique UUID so that it can be tracked throughout the system.

While optional, this is a key feature that enables powerful features from analytics, to logging, to cross-referencing actions between lists in a deterministic way. 

It is assumed this will be done with tooling, either automatically or as a script, but it can also be done manually if needed.

Reflect

This one is either part 4 or 5 depending on your perspective. 

But this is also where GTD aligns with Agile in their emphasis on _regular reflection and review_.

Both systems stress the importance of periodic review and periodically doing the three steps above at the appropriate times:
- Capture: Always happening, should be near effortless and be the first thing you do when something new comes up
- Clarify: Requires the most decision making of the other steps
- Sometimes you are working with others and clarifying actions can be a group activity
- Other times it is benficial to clarify actions as soon as you write them while the context is fresh
- other times the purpose of the inbox is important and it is a mark of discipline to NOT clarify actions on particularly thorny days and save this work for more dedicated review times.
- Organize: Like clarify, this often depends on the context but should be done in regular intervals
- If you do organize daily, restrict it to once or twice a day to avoid decision fatigue
- Weekly reviews are also a good default and when the bulk of the organizing is often done
- Monthly reviews can be good for full refactors of existing outcomes to ensure everything is still aligned with your goals

The real importance of reflection is that it is done _regularly_ such that it becomes a core _habit_ you build within your system. This means it must be deeply aligned with your workflow and schedule and will be a core part of how the workflow is built around you rather than the other way around.

While a good default is a weekly review, agile does this process bi-weekly on average which is normal for teams doing this process, while some individuals fine building a daily ritual to be core to how they keep aligned through the day.

On Analytics

This is where a robust system of review is crucial for success. We want to look back at what we have done while planning future intentions, so tooling may project the workspace into JSON, RDF, tables, or an external analytical store. These are read models over the authoritative workspace unless an explicit mutation contract says otherwise.

Blocked and Dependent Actions

One particular place where tooling makes this easier is the ability to identify when some actions may be blocked or depend upon one another which will help us identify bottlenecks in our workflow and ensure we are focusing on the right actions at the right time.

This process is difficult to do by hand with a file of strings, but trivially easy with even a simple database.

On Scheduling

This is also the stage where active use of the calendar bcomes key to managing the list of actions as reviewing both our upcoming and past intentions can often bring up new actions or remind us of key other actions we are trying to do

Engage

Any other point in time that you are not doing one of the above phases, you are in the "Engage" phase where you are using your system as a declarative action system where you simply look at your list of actions and complete them as time permits

Here we are embodying the core principles of deep work to keep us aligned on the next action we want to focus on, knowing that we have reviewed the relevant inboxes and have decided what can and should be done ahead of time.

Agenda View

Another core usecase for the system is being able to generate an "agenda view" of the actions that need to be done today or in the near future.

This is not simply actions that are due/do today, but also represents actions that have no open dependencies, are within the proper context you are in, and are the top priority actions you want to focus on. All of this requires not just a data system, but a robust one that is able to leverage the relationships between actions as a graph and do the hard work of filtering down to the right actions for you to focus on.

In many ways, this is the core "why" beind the whole system as we want to make generating, maintaining, and updating this list as easy and effortless as possible so that we are mostly focused on completing actions rather than managing the system itself.

If all goes well, this list should be where you spend the majority of your time as you work through your day.

This list will include recurring and one-off actions, as well as actions that have no due date but are of high priority of which can be done within the current context/timeframe.

Arhiving

Archival is a sparate activity from closure, a record can be closed however long we want to before it is "archived" and for some formats, the distinction isnt needed as much if the state is maintained within a database. however, for file-based interfaces it is often easier to move the closed records into some sort of "archive" for external storage and querying such that the whole graph can be queried at a a later time such as is outlined in the [workspace spec](./workspace.md)

Workflow

Now that we have covered the overarching stages, we want to get a bit more granular around the relationships between various properties around the actions and how they are meant to communicate our intent

Charters

Charters follow a fairly simple workflow as they are higher level than the plan and thus are expected to see less daily alteration. still, there is still some workflow to consider.

State

Charter state is a local fact governing whether its work stream is admitted for engagement:

  • New — defined but not yet admitted. This is the default when state is omitted from source.
  • Active — eligible for engagement, provided every ancestor Charter is also Active.
  • Blocked — cannot currently advance.
  • Closed — finished and terminal.
  • Cancelled — abandoned and terminal.

States never cascade implicitly. Changing a Charter’s state does not rewrite any descendant Charter or Action. Effective eligibility is nevertheless inherited: a Charter beneath a non-Active ancestor is not admitted even when its own local state is Active.

Cross-level contradictions remain visible and are diagnosed rather than silently normalized:

  • an Active descendant Charter or InProgress Action beneath New or Blocked ancestry is a warning;
  • an open descendant Charter or Action beneath Closed or Cancelled ancestry is a violation.

An Active Charter with no Actions is valid and does not require a warning.

Closure

Before closing or cancelling a Charter, its open descendant work should normally be completed, cancelled, moved, or otherwise reconciled. Implementations must not automatically complete or cancel descendants as an implicit consequence of the Charter transition. A separate explicit batch operation may be offered when the user deliberately requests cascading mutations.

Plans

Plans are VEVENT calendar projections of Action blocks and Habits. Native text owns the work; calendar edits can change the projected fields, not local workflow facts.

An unscheduled Action has no Plan. Assigning or changing @ creates or updates its one-off Plan; a calendar schedule edit updates @. Clearing @ removes the Plan without closing the Action. Deleting an established Plan unschedules the Action without deleting or cancelling it. An untracked snapshot’s absence alone is not evidence of deletion.

A genuinely new, unrelated VEVENT in an owned collection creates a scheduled, not-started Action in its owning Charter, using SUMMARY and human DESCRIPTION. Its arbitrary calendar UID is never mistaken for native Action identity.

Name, human description, planned start/end, recurrence and exceptions reconcile independently. Safe changes in one field continue while another conflicts. Agreeing values converge; differing values are presented for resolution, never silently decided by timestamps.

Habits

A Habit is a top-level line with R: in its charter’s .habits.actions. Any open state generates: [ ] not started, [-] in progress and [=] blocked. Only [x] completed and [_] cancelled stop generation, including catch-up; each records its closed date with %. Closing the Habit does not close any occurrence. There is no pausing, and [=] has no special generation meaning. To stop for a while, close the Habit and recreate it later.

An Action is materialized for every arrived slot, whether earlier occurrences are done or not. Missed occurrences stay open until individually completed or cancelled. Reads stay pure. Future slots are read-only projections, never editable Action rows. Catch-up may be incremental, but interruption or a limit on work per operation must not drop slots. Repeating generation must not duplicate active or archived occurrences.

Only the root recurs. Its children are a template forest stamped below each occurrence, not recurring calendar components. Alternatively, a leading template: <name> directive in its description names a workspace template. Children win when both are present, with a warning. Template steps have persisted, stable native UUIDs; title, order and path are not their identity.

A template does not recur and its steps do not depend on their ancestors. Generating from a template, by stamping an occurrence or applying it on demand, refuses a template with R: on any of its lines (lint E002) or a step whose < resolves to the Habit or another of the step’s ancestors (lint E009), naming each offending line’s file and line. A refused Habit generates nothing until it is fixed; its arrived slots then materialize as usual. Steps may still depend on sibling steps.

Each occurrence’s id derives from (native Habit id, original slot); step ids additionally derive from stable template-step ids. The canonical encoding is in the ICS specification. Repeated stamping, step rename and reorder do not duplicate steps. Template edits affect later stamps, never overwrite existing occurrence trees.

The : window is never synchronized. Each occurrence keeps the window’s offset from the repeated block, in that block’s time frame: date offsets in calendar days, floating offsets in wall time, zoned offsets in the series zone. Children then inherit effective windows normally.

Rule edits change subsequent expansion, preserving all existing active and archived occurrence facts and ids. Newly introduced arrived slots must still materialize; progress under a previous rule cannot hide them. Exclusions skip unmaterialized excluded slots, never silently delete materialized work. A completed or cancelled Habit makes no further occurrences, including catch-up.

Series time/rule edits target the Habit. RDATE, EXDATE and time frames are preserved with it. A single-occurrence edit, including a rename, targets only its Action; edits for an occurrence not yet materialized must survive until it exists. Rescheduling changes the matching RECURRENCE-ID override and the materialized Action, preserving the original slot as identity.

Kind changes and identity

Calendar changes between one-off and recurring work are never silently applied. The user must be able to review the resulting block and effects on children, dependencies, state, priority and contexts before authorizing the change.

  • An accepted one-off → recurring change retains the Action’s native UUID as the Habit id; no duplicate old Action remains. The first occurrence has its own derived id, not the old Action’s id.
  • An accepted recurring → one-off change ends the Habit. The newest open occurrence keeps its id and becomes the one-off Action; older open occurrences remain open for manual completion or cancellation. The resulting block must be visible, including when a calendar client returns to the original series start. If no open occurrence exists, the one-off Action keeps the Habit’s UUID, as a text kind change does and as a calendar keeps one UID when an event switches between recurring and single, so every device derives the same id.
  • A text kind change moves the line between the ordinary actions file and habits file, adding or removing R: and retaining its UUID. It does not adopt that line as a generated occurrence.

Transport UID replacement and this and following splits do not establish native identity. Retaining native identity after replacement requires an explicitly user-confirmed link, never automatic matching. Ambiguous relationships remain unresolved; a suspected replacement with no candidate stays held without creating a new entity until the user supplies a link. A possible match is not proof of identity.

Plans vs Actions

Plans and Actions are distinct, linked concerns:

  • Plans live in .ics as projections; native Habits and sidecars hold recurrence and occurrence deviations.
  • Actions live durably in .actions; hierarchy, dependencies, and unmapped ClearHead workflow semantics remain local there.
  • Not every Action has a Plan; ad-hoc and intentionally unscheduled Actions are valid.
  • VEVENT reconciles blocks, names, human descriptions, recurrence and exceptions field by field. State, completion, priority and contexts stay local; no peer silently wins conflicts.
  • Kind changes require user authorization; native identity and existing history are preserved as described above.

See the workspace specification for file placement and archival, the iCalendar schedule specification for format and identity semantics, and the ontology for the Plan–Action relationship.

Actions

Actions will be the primary record type that people will interact with day-to-day and as such understanding their workflow is key

State

Action state records the lifecycle of one concrete act:

  • NotStarted — open and not presently underway; the default for a new Action.
  • InProgress — presently underway. It is not another spelling of Charter Active.
  • Blocked — open but unable to advance; explicit dependencies are preferred when they accurately identify the blocker.
  • Completed — finished successfully and terminal.
  • Cancelled — intentionally abandoned and terminal.

A common workflow is NotStarted -> InProgress -> Completed; blocked or cancelled paths remain valid. State transitions are local facts and do not implicitly mutate parent or child Actions.

Ready is derived and must not be stored as an Action state. A NotStarted Action is ready only when:

  1. its owning Charter and every ancestor Charter are Active;
  2. every predecessor is satisfied (Completed or Cancelled); and
  3. applicable schedule and context constraints permit execution.

A trusted next-work projection surfaces admitted InProgress Actions before ready NotStarted Actions. Contradictory InProgress work beneath non-admitted Charter ancestry is reported as a coherence finding rather than silently treated as ready.

On Closure

Closure and archival are separate transitions. Completing or cancelling an Action changes that concrete Action’s lifecycle state; archival then moves the terminal record into durable history.

A one-off Plan is not a second lifecycle object. Action completion remains local. Archiving an occurrence snapshots its native Habit id, transport link and canonical slot into durable metadata. Closure does not advance a single live token: every arrived slot is independent. Future read-only projections are not Actions and are never archived.

On Child Actions

Parent and child Action states remain independently asserted; neither direction cascades implicitly. Tooling may derive facts such as “subtree complete” or omit an open container from a next-work projection while an executable descendant exists, but those projections do not change the parent’s stored state.

A terminal parent with open descendants is contradictory and should be reported for deliberate reconciliation. An explicit command may offer a reviewed batch transition, but merely completing or cancelling one Action must not rewrite its relatives.

Priority

Priority uses the RFC 5545 range directly: 1 is highest and 9 is lowest. An omitted priority means undefined. This direct scale preserves VTODO interoperability without a lossy conversion table.

Priority is ordering guidance, not an encoded Eisenhower quadrant. Urgency may be represented by dates and importance by the surrounding charter or objective. Work that no longer deserves attention should be explicitly cancelled rather than hidden behind a special priority value.

Engineering Process

The stages above describe how *users* move actions through the system. This section describes how *we* should move engineering next-actions through it, because the same discipline that keeps a personal list honest keeps a charter honest.

The Call-Site Sweep Done-Gate

A core capability is not done until every call site that duplicated it has been swept onto it, and a guard exists so the old pattern cannot silently reappear.

This was learned the expensive way on the core-seam charter (2026-07-11): several next-actions had been marked `[x]` with plausible, detailed descriptions of what "landed" — a precedence-bug fix, subtree-close semantics moved to core, a durability guard — and none of it existed anywhere in the repository. No commit, no stash, no other branch. One of them was a live user-facing bug marked fixed while still reachable through four different commands.

The pattern that let this happen: a capability got added to core, but the CLI's own call sites kept their inline, duplicate implementation next to it. Nothing forced convergence, so "the core function exists" was mistaken for "the capability is done." Two capabilities can coexist for a long time — the description alone can't tell you which one a caller actually goes through.

The done-gate this charter proposes, going forward:

1. **Implement the capability once**, in the layer that should own it (core, in the core-seam charter's case).
2. **Sweep every call site onto it.** Find each place the old inline/duplicate logic lived and delete it, not just add a new path beside it. If a caller can still reach the old code, the sweep is not done.
3. **Add a guard** — a test, a lint, a grep-check — that fails if the old pattern reappears. Not every capability needs one (a guard is proportional to how easy the old pattern is to reintroduce and how costly a regression would be), but if you needed to sweep it once, assume someone will reintroduce it by accident later.
4. **Verify the claim against the code, not the description**, before marking it done. A next-action's description is a claim about the world; `git log` and the source tree are the world. If you can't point at a commit and a diff that matches the description, it isn't done yet — write down what's actually true instead of what was planned.

Step 4 is the one that would have caught the 2026-07-11 gap immediately: none of the falsely-completed items had a matching commit. Checking is cheap; trusting a well-written description is what's expensive.