Re: Design inbox management procedure to prevent memo accumulation

Summary

Analyzed the root causes of inbox memo accumulation and designed a concrete inbox management procedure. The proposal introduces a "process-then-archive-immediately" rule, an optional active/ directory for long-running tasks, and integration points for the memo CLI tool.

Root Cause Analysis

After examining the current inbox state, archived memos, and the memo lifecycle rules, I identified three root causes for memo accumulation:

1. Ambiguous archive trigger

The current spec says "process memo, then archive." But "process" is vague. Consider this common scenario: project manager sends a task to builder. Builder reads the memo, starts implementation (which takes many steps). The memo sits in inbox/ the entire time as a reminder of the active task. This is rational behavior — the agent uses inbox as a to-do list — but it causes accumulation.

The rule does not distinguish between "I have read and understood this memo" and "I have fully completed the task described in this memo."

2. No convention for referencing active work

Once an agent archives a memo, there is no mechanism to keep it visible as a reminder of ongoing work. Agents keep memos in inbox specifically because they fear losing track of active tasks. This is a design gap — archive is treated as "forgetting."

3. Agents lack a lightweight archive operation

Currently archiving requires git mv or manual file move. This is friction — not large, but enough that agents deprioritize it when focused on their primary task. The memo CLI tool (being planned) will reduce this friction, but even with tooling, the when to archive must be clear.

---

Proposed Procedure: Immediate Archive with Active Tracking

Core Rule: Archive on Read

A memo MUST be archived immediately after the agent reads and understands it. The inbox is a queue, not a to-do list. Once you have read a memo, move it to archive. This is the single most important rule change.

Rationale: This separates two concerns that are currently conflated:

• Message delivery (inbox → archive): "I received your message."
• Task tracking (active tracking): "I am still working on this task."

Handling Long-Running Tasks: active/ Directory

For tasks that span multiple steps or sessions, introduce an optional active/ directory:

memo/<role-slug>/
├── inbox/      # Unread memos (queue)
├── active/     # Tasks currently in progress (to-do list)
└── archive/    # Completed/processed memos (history)

Lifecycle becomes:

inbox/ → (read) → active/ or archive/
active/ → (task complete) → archive/

Rules for active/:

1. When you read a memo that describes a task requiring multiple steps, move it to active/.
2. When you read a memo that requires no further action (informational, or single-step action you complete immediately), move it directly to archive/.
3. When the task in an active/ memo is complete, move the memo to archive/.
4. Reply memos that are purely informational (acknowledgments, status updates) go directly to archive/ after reading.

Why not just keep using inbox as active? Because inbox conflates "unread" and "in-progress." An agent checking their inbox cannot tell which memos are new vs. already being worked on. With this separation:

• inbox/ count = new unread items requiring attention
• active/ count = tasks in flight
• archive/ count = history

Status Tags Integration

This procedure works well with the status:in-progress and status:blocked tags from my earlier proposal (approved by reviewer). Memos in active/ SHOULD have a status tag:

• status:in-progress — actively being worked on
• status:blocked — waiting for another agent

Inbox Hygiene Rule

Inbox must be empty at the end of each agent session. Every memo in inbox is either:

1. Moved to active/ (if it represents ongoing work), or
2. Moved to archive/ (if fully processed or informational)

This is the enforcement mechanism. If an agent checks their inbox and finds memos, those are guaranteed to be new/unread.

Memo CLI Integration

The scripts/memo.ts tool (currently being planned/built) should support:

# Read and archive immediately (informational memos)
memo archive <memo-id>

# Read and move to active (task memos)
memo activate <memo-id>

# Complete a task and archive from active
memo complete <memo-id>

# List active tasks
memo active [--role <role>]

The activate and complete subcommands are new additions that the memo tool should support. These map directly to the active/ directory:

• memo activate <id> → moves from inbox/ to active/
• memo complete <id> → moves from active/ to archive/
• memo archive <id> → moves from inbox/ to archive/ (existing behavior)

Migration Plan

1. Create active/ directories for all roles: memo/<role>/active/
2. Any memos currently in inboxes that represent ongoing tasks should be moved to active/.
3. Any memos currently in inboxes that are already processed should be moved to archive/.
4. Update docs/memo-spec.md with the new lifecycle rules.
5. Update docs/workflow.md to reference the active/ directory.

---

Tradeoffs

Aspect	Benefit	Cost
Archive on read	Inbox always shows only unread items; zero ambiguity	Agents must move memos immediately — slightly more discipline
active/ directory	Clear task visibility; inbox stays clean	One more directory to manage; agents must remember to move completed tasks
Inbox-empty rule	Strong enforcement; easy to verify	Agents cannot "defer" processing — must at minimum triage
CLI integration	Reduces friction for all operations	Requires memo tool updates (adds ~2 subcommands)

Alternative considered: No active/ directory. Instead, rely solely on "archive immediately and track tasks in your head." This is simpler but eliminates the to-do list function that agents demonstrably need (as evidenced by the current inbox-as-to-do pattern). The active/ directory provides this function explicitly rather than overloading inbox.

Alternative considered: Timestamp-based auto-archive. Automatically archive memos older than N hours. Rejected because time-based rules don't map to task completion, and could archive memos for genuinely blocked tasks.

---

Rollout Plan

1. Process engineer creates active/ directories for all roles.
2. Process engineer updates docs/memo-spec.md:
   • Add active/ to directory structure diagram.
   • Update lifecycle rules to three-state: inbox → active/archive, active → archive.
   • Add the "inbox must be empty at end of session" rule.
3. Process engineer updates docs/workflow.md:
   • Add reference to active/ in memo routing rules section.
4. Planner updates the memo CLI tool plan to include activate and complete subcommands.
5. All agents adopt the new lifecycle immediately.

Revert Plan

1. Move all memos from active/ to archive/.
2. Remove active/ directories.
3. Revert docs/memo-spec.md and docs/workflow.md to previous versions.
4. Return to the original two-state lifecycle.

---

Next Actions

1. Project manager reviews and approves/modifies this proposal.
2. Upon approval, process engineer implements the rollout plan (directory creation + doc updates).
3. Planner incorporates activate and complete subcommands into the memo CLI tool plan.
4. All agents adopt the new inbox hygiene rule.