Erich Blume
1c94a08cda
A new explanation doc making the task model explicit: lifecycle state
(outstanding → done/dropped) is orthogonal to attention (white/orange/red/
blue), attention only matters while outstanding, and On Deck (blue) is a live
"later" task — NOT the same as dropped ("let go", terminal). Covers delete/
tombstone (soft-delete that keeps the context doc) and a table of where each
task shows up (agenda / search / export). Cross-links design §6.2/§6.3 and
tech-spec §4.3/§7/§8.1/§12; wired into the explanation index.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4.8 KiB
| title | modified | tags | ||
|---|---|---|---|---|
| Task Lifecycle | 2026-06-03 |
|
Task Lifecycle
How a committed task moves through heph — and the one idea that makes the whole thing click: a task has two independent axes, not one status field.
Scope: this is about committed tasks (the things that appear in "what is next"). Ephemeral context items (the
- [ ]checklist lines inside a task's context doc) are a separate concept — see design §6.3.
The two axes
| Axis | Values | Question it answers |
|---|---|---|
| Lifecycle state | outstanding → done / dropped |
Is this still a live thing? |
| Attention | white · orange · red · blue |
How much should it be on my mind right now? |
They are orthogonal. Attention only means anything while a task is
outstanding — a done task has no useful attention. This separation is what
keeps the system honest (see design §6.2): you decide whether you're still
doing something separately from how loud it should be.
Lifecycle state
outstanding— a live commitment. Every task starts here. Only outstanding tasks appear in the agenda (the §8.2 views, project views, "what is next").done— you did it. Terminal. For a recurring task, completing rolls it forward to its next occurrence with a fresh checklist (it reappears as a new outstanding instance — see design §3.3 and tech-spec §4.4), rather than ending.dropped— you've decided not to do it ("let it go"). Terminal, and the sibling ofdone: "didn't do" vs "did". The distinction fromdoneis kept on purpose. Dropping a recurring task ends it — it does not roll forward (onlydonerolls forward).
Both done and dropped are "not outstanding", so both leave every agenda
surface — but they remain in the store as a record.
Attention (only while outstanding)
The colors, thought of as feeling, not number (design §6.2):
- white — doable once its do-date arrives (the default).
- orange — top of mind (keep ≤ ~6, reconfirm daily).
- red — top of mind and a consequence exists if it's late (consequence, not importance).
- blue — On Deck — a backlog item, deliberately cooled. Still outstanding — a real, live task you intend to do later. Blue is the pressure-relief valve that keeps the active set light.
The common trap is conflating blue (On Deck) with dropped. They are not the same: blue = "later", dropped = "not at all". The §6.2 blue keep/drop review is precisely the act of looking at your On Deck pile and, for each item, either keeping it blue ("later") or dropping it ("let go").
Delete (tombstone) — a third thing, below the lifecycle
dropped still leaves a record. Tombstoning (delete) goes further: it marks
the task node tombstoned and removes it from everything — the agenda,
full-text search, and export. It is a soft delete (the row is retained with
a flag, recoverable at the database level, and CRDT-safe — heph never hard-deletes,
see tech-spec §12), but for all practical purposes the task is gone.
Deleting a task tombstones only the task node — its canonical-context doc (your notes/checklist for it) is kept, so deleting a task doesn't throw away the writing attached to it.
Where each task shows up
This is the practical payoff of the model — what's visible where:
| outstanding (incl. blue / On Deck) | dropped | tombstoned (deleted) | |
|---|---|---|---|
Agenda views (next / list / view / project) |
✅ shown | ❌ gone | ❌ gone |
Full-text search (/) |
✅ | ✅ still findable | ❌ gone |
| Export / raw store | ✅ | ✅ retained | ❌ (flagged deleted) |
A dropped task is gone from all agendas (including project views) but
stays findable in search — so "let go" is recoverable if you change your mind,
without cluttering your working set.
How you move a task between states
The model is surface-agnostic; the gestures differ per surface. In the TUI (tech-spec §8.1):
| Gesture | Effect |
|---|---|
a |
capture a new task → outstanding |
A |
cycle attention (white → orange → red → blue) |
b |
push to blue / On Deck (still outstanding) |
x |
done (a recurring task rolls forward) |
s |
skip a recurring task to its next occurrence (no completion logged) |
d |
drop (terminal "let go") |
D |
delete / tombstone (with confirmation) |
The CLI mirrors these (heph done / drop / skip / attention /
node rm), and a context item can be promoted into a brand-new outstanding
committed task (design §6.3).