1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
#+TITLE: Inbox Zero Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-06-13
* Overview
The roam global inbox (=~/org/roam/inbox.org=) is Craig's cross-project GTD capture: one shared file every project can see. This workflow routes each inbox item to the project that owns it. The current session claims only the items belonging to THIS project, files them into the project's =todo.org=, and removes them from the shared inbox. Everything it doesn't own stays. The aspiration is inbox zero: over time, every item lands in its owning project.
This is NOT =process-inbox.org=. That workflow handles the project's own =inbox/= directory (handoffs from other projects, scripts, Craig). This one handles the single global =roam/inbox.org= and the cross-project routing a shared file creates.
This is also distinct from the wrap-up inbox/transcript routing feature (which moves session-filed keepers between projects). This routes the shared roam capture file by ownership prefix.
** Scope: single-destination (v1)
This version routes each item to its one owning project, identified by an explicit =<project>:= heading prefix. The multi-project domain-aware mode, which would guess the owner of every unprefixed item and empty the whole inbox in one run, is deferred (see "Deferred: domain-aware routing" at the end). v1 claims only what's prefixed for the current project, surfaces the rest, and never guesses.
** Three callers
Reused from three callers so the steps live in one place:
- *Startup* (read-only nudge) — count the items, identify which appear related to this project, surface both numbers, offer processing as one of the startup options. Never auto-files.
- *Wrap-up* (Step 3 sub-step) — sweep items that belong here before the cleanup scripts, so imported tasks lint and ride the wrap commit.
- *On demand* — "inbox zero", "empty the inbox", "process the roam inbox", "triage my roam inbox".
Each project touches the roam inbox at least twice a session this way: once at startup, once at wrap-up.
* The ownership rule (the coordination primitive)
The inbox is shared, so the workflow must never let two projects fight over an item or let one project grab another's. Ownership is by explicit prefix:
- =<project>: ...= heading → owned by that project. The current project claims only items prefixed with its own identifier.
- Prefixed for *another* project → leave untouched (cross-project boundary, =protocols.org=).
- *No prefix* → unowned. Never auto-claim. Surface as candidates a human can claim or prefix.
The prefix partition is what makes concurrent triage across projects safe: each project only ever removes its own items, so two sessions editing the inbox touch disjoint lines.
** Resolving this project's identifier (v1)
Use the project root basename plus its common aliases (=.emacs.d= ↔ =emacs=, and the obvious ones: =rulesets=, =work=, =home=). A project may override the inferred set with an =:INBOX_PREFIX:= line in =notes.org='s *Workflow State* section when the basename is fragile (a dot in the name, an alias the inference misses). The explicit override is optional in v1; the durable multi-project resolution is part of the deferred domain-aware mode.
* Phase A — Identify, count, and match
1. Resolve the current project's identifier and aliases (above).
2. Read =~/org/roam/inbox.org=. If absent, silent no-op (the file lives only on machines with the roam clone).
3. Bucket every item under the inbox heading:
- *claimed* — prefixed for this project
- *foreign* — prefixed for another project → leave
- *unowned* — no project prefix
4. *Summarize the scan* (Craig's requirement, every scan): report the total item count in the inbox, then the count that appears related to this project. "Appears related" is the union of claimed items (exact prefix) and any unowned item whose topic plainly concerns this project's domain (a content judgment, surfaced as a candidate, never auto-claimed). Foreign-prefixed items are not "related" — they belong to their owner.
5. If both claimed and related-unowned are empty, report the total and stop (the common case for most wraps).
* Phase B — File each claimed item into todo.org
Apply =process-inbox.org='s discipline against the project's =todo.org=; don't reinvent it:
1. *Status check first.* Already done, or already a task in =todo.org=? → drop it, or fold into the existing task (dated sub-entry per =todo-format.md=). Don't duplicate.
2. *Rewrite* to terse-heading + body per =todo-format.md=.
3. *Priority + tags from THIS project's scheme* — the legend at the top of its =todo.org=, tags from that scheme's allowed set only. The project expresses someday-maybe with =[#D]=; there's no special someday-maybe routing.
4. *File* under the project's Open Work section.
* Phase C — Reconcile the shared inbox
The roam inbox lives in a git repo (=~/org/roam=, auto-synced by the =roam-sync= timer). Edit it carefully:
1. *Pull first* (=git -C ~/org/roam pull --ff-only=). If it can't fast-forward (dirty tree, divergence), surface and stop. Don't auto-stash, auto-merge, or force. Resolve before removing items.
2. *Remove only the claimed items.* Never touch foreign or unowned items.
3. *Commit the roam repo as its own commit* (separate from any project wrap commit): =chore(inbox): route <project> tasks to <project>/todo.org=. Push, or leave for the =roam-sync= timer. Surface a blocked push; don't force.
* Phase D — Surface
Report: moved (with their new priorities and tags), folded, dropped-as-done. Then the residue: foreign items (left for their owners, count only) and unowned items (count plus the headings that appear related to this project, for manual claim or prefix). Same "summarize what we kept" shape.
* Skip conditions
- No =~/org/roam/inbox.org= → silent no-op.
- No claimed and no related-unowned items → report the total, stop.
- Roam pull blocked → surface, stop before editing.
* Caller integration
** Startup (read-only nudge)
Phase A of =startup.org= reads =~/org/roam/inbox.org= and produces the scan summary; Phase C surfaces one line: "Roam inbox: N items total, M appear related to this project — say 'inbox zero' to file them." Offered as one of the priority options. Startup never auto-files; it counts and offers.
** Wrap-up (Step 3 sub-step)
A sub-step at the start of wrap-up Step 3 (before the cleanup scripts, so imported tasks get linted and ride the wrap commit) delegates here for the claimed set. Skip-fast when nothing matches.
* Deferred: domain-aware routing (future work, multi-project)
v1 handles the single-destination case via the prefix rule. The multi-project parts are deferred until the need is real:
1. *Domain-aware empty-it-all mode.* If rulesets held a description of each project's domain, one run could guess the owner of every item (prefixed or not) and empty the whole inbox at once, delivering each item to its owning project's =inbox/= via =inbox-send= (where that project's =process-inbox= gate still decides whether to file it). This turns "inbox zero" from a per-project aspiration into a single command. Open: where the domain map lives (central registry vs each project's =notes.org=), how confident a guess must be before auto-routing vs surfacing, and whether a low-confidence item stays put.
2. *Explicit per-project =:INBOX_PREFIX:= as the durable resolver*, replacing basename inference.
3. *Unowned-item lifecycle* once domain-aware routing exists (no item stays unrouted indefinitely).
4. *Concurrent push contention* on the shared roam repo: the pull-before-edit + ff-only + surface-on-conflict floor may want a retry-once-after-pull.
Take these up when the single-destination version is in use and the multi-project pain is concrete.
|
