Clarify & Organise rework — support split/merge of inbox items

[TMaYaD]

Context

From the task-domain-model proposal docs/proposals/task-model.md §6.4. The current "clarify" flow assumes a 1:1 mapping from inbox item to clarified task. In practice:

• One inbox item often splits into multiple tasks ("Project X" → "draft outline", "send to reviewers", "schedule kickoff").
• Multiple inbox items often merge into one task (the same idea echoing in different contexts at different moments).

The current data model conflates inbox item with task (state == 'inbox' on the todos table), making split/merge UX awkward.

Scope (preliminary — needs design pass)

• Possibly: a distinct InboxItem entity, separate from Task.
• Clarify UI affordances: split one inbox item into N tasks; merge multiple into one.
• Provenance tracking so a clarified task can show "captured from these N inbox items".
• Decide whether merge consumes the inbox items or just links them.

Out of scope

• Voice/AI clarification UX — see Interactive Verbal Clarifier #86, AI-Powered Inbox Triage #61, Conversational Brain Dump #62 (orthogonal: same flow, different surface).

Engineering directive (today)

Until this is implemented, keep code touching the inbox/clarification flow reversible — see proposal §6.4. Don't bake "Inbox is just a Task with clarified=false" into load-bearing assumptions; isolate clarification UI flows behind a notifier/service interface.

References

• Proposal: docs/proposals/task-model.md §6.4.
• Predecessor: Clarify & Organize: Process Inbox to GTD Lists #38 (closed) — first version of clarify flow, 1:1 model.
• Adjacent UX: Interactive Verbal Clarifier #86 (Verbal Clarifier), AI-Powered Inbox Triage #61 (AI Triage), Conversational Brain Dump #62 (Brain Dump).

[capo-the-ai-bot]

Scoping note: when this gets delegated, the first deliverable is a spike only — a written proposal documenting the proposed data model (split-merge link tables vs synthetic parent IDs vs other), migration strategy, and Clarify-flow UX implications. No code lands until the proposal is ratified.

[trixy-the-ai-bot]

Now I have enough context to write a thorough plan. Here it is:

---

Implementation Plan: Issue #184 — Inbox Split/Merge

Current State

The todos table doubles as both inbox and task storage, distinguished only by todos.clarified (false = inbox, true = task). InboxDao.processInboxItem flips the existing row in-place — always a 1:1 mapping. There is no provenance record and no way to split or merge. The clarification logic is embedded directly in FocusSessionPlanningNotifier (violating the issue's reversibility directive).

---

Phase 0 — Service Layer Isolation (No UX Change)

Goal: satisfy the engineering directive before adding any new features.

Extract a ClarificationService abstract class so the clarification contract is decoupled from its implementation. FocusSessionPlanningNotifier currently calls InboxDao and TodoDao directly for all clarification operations; move those calls behind the interface.

New files

app/lib/services/clarification_service.dart        — abstract interface
app/lib/services/inbox_clarification_service.dart  — concrete DAO-backed impl

ClarificationService contract (initial — grows in later phases):

abstract class ClarificationService {
  Future<void> processToNextAction(String inboxItemId, {required String userId, ...});
  Future<void> processToWaitingFor(String inboxItemId, String waitingFor, {required String userId});
  Future<void> processToMaybe(String inboxItemId, {required String userId});
}

Modified files

• app/lib/providers/focus_session_planning_provider.dart — inject ClarificationService via a Riverpod provider; remove direct DAO calls from clarification paths
• app/lib/database/daos/inbox_dao.dart — no logic change; called only via the service now

Tests — no new behavior to test; existing integration tests must still pass.

---

Phase 1 — Provenance Schema

Goal: every clarified task records which inbox item(s) it came from.

Backend — Alembic migration

CREATE TABLE todo_provenance (
  id              UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  task_id         UUID        NOT NULL REFERENCES todos(id) ON DELETE CASCADE,
  source_inbox_id TEXT        NOT NULL,   -- soft ref; inbox row may be deleted
  source_title    TEXT        NOT NULL,   -- snapshot at clarification time
  user_id         UUID        NOT NULL,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ON todo_provenance (task_id);
CREATE INDEX ON todo_provenance (user_id);

source_inbox_id is TEXT (not a FK) because the original inbox row may be deleted when consumed by a split or merge.

New files

• backend/alembic/versions/00NN_add_todo_provenance.py
• backend/app/todos/models.py — add TodoProvenance SQLAlchemy model

Client schema

Add to app/lib/database/powersync_schema.dart:

ps.Table('todo_provenance', [
  ps.Column.text('task_id'),
  ps.Column.text('source_inbox_id'),
  ps.Column.text('source_title'),
  ps.Column.text('user_id'),
  ps.Column.text('created_at'),
])

Add TodoProvenances Drift table class in the Drift schema; regenerate .g.dart.

New file: app/lib/database/daos/provenance_dao.dart

class ProvenanceDao {
  Future<void> insertProvenance(String taskId, String sourceInboxId, String sourceTitle, String userId);
  Stream<List<TodoProvenance>> watchProvenance(String taskId, String userId);
}

---

Phase 2 — 1:1 Clarification with Provenance (Existing Flow, Enhanced)

Goal: write a provenance row every time the existing 1:1 clarification runs. No UX change.

In InboxClarificationService, wrap each processInboxItem call in a transaction:

await db.transaction(() async {
  await inboxDao.processInboxItem(id, userId: userId, intent: intent, ...);
  await provenanceDao.insertProvenance(id, id, originalTitle, userId);
  // task_id == source_inbox_id because the same row is promoted in-place
});

For in-place promotion (same row), task_id == source_inbox_id. The provenance query on the task detail screen filters these out of the display (no point showing "captured from itself").

Tests

• Unit: InboxClarificationService.processToNextAction writes one provenance row
• Regression: existing E2E clarification flow still passes

---

Phase 3 — Split: One Inbox Item → N Tasks

Data model

1. Insert N new todos rows (clarified = true, intent set)
2. Delete the original inbox item
3. Insert N todo_provenance rows, each pointing task_id → original inbox item id + title

All three steps in a single DB transaction.

Service layer

Add to ClarificationService:

Future<void> splitInboxItem(
  String inboxItemId,
  List<SplitTaskDraft> drafts,  // title, intent, energy, estimate, dueDate, notes
  String userId,
);

SplitTaskDraft is a plain value object. The concrete implementation is a single atomic transaction in InboxClarificationService.

UI

_ClarifyCard (inbox_clarification_step.dart) gains a secondary action:

[ Split into multiple tasks… ]   ← text button, below the PROCESS TO section

Tapping opens SplitInboxItemSheet (modal bottom sheet, or full-screen route on small devices).

New file: app/lib/screens/clarify/split_inbox_item_sheet.dart

Layout:

• Header showing original item title (read-only, for context)
• Scrollable list of draft rows — each has: title text field + intent chip selector (Next / Maybe / Waiting For)
• "+" button appends a new draft (pre-filled empty)
• Minimum 2 drafts required before confirm is enabled
• "Create N tasks" confirm button at bottom
• On confirm → calls ClarificationService.splitInboxItem → closes sheet → inbox updates reactively

Tags are not copied to child tasks in the MVP. Energy and time estimate are optional per draft.

Tests

• E2E: capture 1 inbox item → split into 3 → verify 3 clarified tasks exist, original inbox row gone, 3 provenance rows recorded
• Unit: SplitInboxItemSheet — confirm disabled when < 2 drafts, enabled at 2+
• Integration: InboxClarificationService.splitInboxItem is atomic (failure mid-transaction leaves inbox item intact)

---

Phase 4 — Merge: N Inbox Items → One Task

Data model

1. Insert 1 new todos row (clarified = true)
2. Delete all N source inbox items
3. Insert N todo_provenance rows, each linking the merged task to one source inbox item

Merge consumes (deletes) the source inbox items — they disappear from the inbox immediately. The provenance table preserves their titles as a record.

Service layer

Add to ClarificationService:

Future<void> mergeInboxItems(
  List<String> inboxItemIds,
  MergedTaskDraft draft,  // final title, notes, intent, energy, estimate
  String userId,
);

UI — Inbox screen merge mode

InboxScreen gains a merge-mode toggle:

• Toggle button in the app bar (e.g. multi-select icon)
• In merge mode: items show checkboxes; app bar shows selected count; a "Merge N items" button appears at the bottom of the screen
• Selecting < 2 items keeps the button disabled

Tapping "Merge N items" opens MergeInboxItemsSheet.

New file: app/lib/screens/clarify/merge_inbox_items_sheet.dart

Layout:

• List of selected item titles (read-only)
• Editable title (pre-populated from the first selected item)
• Notes field
• Intent chip selector
• Energy / time estimate pickers
• "Create merged task" confirm button

On confirm → calls ClarificationService.mergeInboxItems → clears merge mode → inbox updates reactively.

Merge during planning ritual: deferred. The clarification step processes items one at a time (FIFO). Adding multi-select there complicates the ritual flow. Use the Inbox screen as the only merge surface for now.

Tests

• E2E: capture 3 inbox items → open inbox → enter merge mode → select all 3 → merge → verify 1 clarified task, 3 inbox items gone, 3 provenance rows
• Integration: InboxClarificationService.mergeInboxItems is atomic
• Unit: MergeInboxItemsSheet — title pre-populated correctly, confirm disabled when title empty

---

Phase 5 — Provenance Display (Task Detail)

task_detail_screen.dart — add a "Captured from" section:

• Shown only when ProvenanceDao.watchProvenance returns rows and task_id != source_inbox_id (i.e. not a trivial in-place promotion)
• Collapsed by default (ExpansionTile)
• Shows source item titles as read-only chips
• Label: "Captured from N inbox item(s)"

No new files needed.

---

File Map

File	Change	Phase
app/lib/services/clarification_service.dart	New — abstract interface	0
app/lib/services/inbox_clarification_service.dart	New — concrete impl	0
app/lib/providers/focus_session_planning_provider.dart	Delegate to service	0
backend/alembic/versions/00NN_add_todo_provenance.py	New migration	1
backend/app/todos/models.py	Add TodoProvenance model	1
app/lib/database/powersync_schema.dart	Add todo_provenance table	1
app/lib/database/drift_schema.dart	Add TodoProvenances Drift table	1
app/lib/database/daos/provenance_dao.dart	New DAO	1
app/lib/database/daos/inbox_dao.dart	Called via service only	0–2
app/lib/screens/planning/steps/inbox_clarification_step.dart	Add "Split" affordance	3
app/lib/screens/clarify/split_inbox_item_sheet.dart	New widget	3
app/lib/screens/inbox/inbox_screen.dart	Add merge mode	4
app/lib/screens/clarify/merge_inbox_items_sheet.dart	New widget	4
app/lib/screens/task_detail/task_detail_screen.dart	"Captured from" section	5
docs/ARCHITECTURE.md	Update task domain model section	All
docs/REQUIREMENTS.md	Add split/merge requirements	All

---

Open Decisions Before Implementation

1. Split sheet surface: bottom sheet (simpler) vs. full-screen route (more room for ≥5 drafts)? Recommend full-screen route to avoid keyboard/layout conflicts.
2. Tag inheritance on split: should tags from the source inbox item be pre-applied to all child tasks? Simpler MVP says no; easier to add later.
3. Merge in planning ritual: currently deferred. Re-evaluate once the inbox screen merge is shipped and UX patterns are settled.
4. Provenance display threshold: show "Captured from" only when N > 1 sources, or always? Recommend: only when N > 1 (single-source is the boring default case, not worth surfacing).

---

Implementation Order

Phase 0  →  Phase 1  →  Phase 2  →  Phase 3  →  Phase 4  →  Phase 5
(isolate)   (schema)    (1:1+prov)  (split)     (merge)     (display)

Each phase leaves the app in a releasable state. Phases 0–2 have no visible UX change and can ship as an internal cleanup PR. Phases 3 and 4 can ship independently once Phase 2 is merged.

[capo-the-ai-bot]

Feedback for revision:

1. Scope this to spike-only deliverable (per the scoping comment above)

The current plan reads as a 6-phase implementation plan. Per the scoping note, the first deliverable is the proposal itself — the data-model design, migration approach, and Clarify-flow UX implications, written down for ratification. Do not start Phase 0 or write code until the user ratifies.

Re-frame the comment: present Phases 0–5 as the proposed sequencing, but make clear nothing is implemented until the user explicitly approves and applies ready-for-development.

2. Skip provenance for trivial 1:1 in-place promotions

Phase 2 inserts a provenance row even when task_id == source_inbox_id (the in-place promote case). That's row noise — every clarification writes a redundant self-pointer. Recommend: only insert todo_provenance rows when the operation is actually split or merge (task_id != source_inbox_id, or > 1 source).

This also simplifies Phase 5: the "Captured from" section's existence test becomes "any provenance rows exist for this task" — no need for the task_id != source_inbox_id filter.

3. Tag-inheritance decision belongs to the source proposal, not the plan

Open Decision #2 ("should tags be copied to child tasks on split?") is a product call. The originating proposal at docs/proposals/task-model.md §6.4 (referenced in the issue body) likely has a stance — read it and align rather than picking "no" by default. If the proposal is silent, surface the question to the user explicitly rather than embedding it in the plan as resolved.

Otherwise

The provenance-table design is sound, the service-layer extraction is good engineering hygiene, the Phase 4 "merge consumes inbox items" semantics is the right call, and the open decisions list is well-articulated.

Please revise.

[trixy-the-ai-bot]

Implementation Plan: Issue #184 — Inbox Split/Merge

Status: Proposal — awaiting ratification.
Nothing below is implemented. Phases 0–5 describe the proposed sequencing. Work begins only after the user explicitly approves and applies ready-for-development.

---

Current State

The todos table doubles as both inbox and task storage, distinguished only by todos.clarified (false = inbox, true = task). InboxDao.processInboxItem flips the existing row in-place — always a 1:1 mapping. There is no provenance record and no way to split or merge. The clarification logic is embedded directly in FocusSessionPlanningNotifier (violating the issue's reversibility directive).

---

Proposed Sequencing

Phase 0 — Service Layer Isolation (No UX Change)

Goal: satisfy the engineering directive before adding any new features.

Extract a ClarificationService abstract class so the clarification contract is decoupled from its implementation. FocusSessionPlanningNotifier currently calls InboxDao and TodoDao directly for all clarification operations; move those calls behind the interface.

New files

app/lib/services/clarification_service.dart        — abstract interface
app/lib/services/inbox_clarification_service.dart  — concrete DAO-backed impl

ClarificationService contract (initial — grows in later phases):

abstract class ClarificationService {
  Future<void> processToNextAction(String inboxItemId, {required String userId, ...});
  Future<void> processToWaitingFor(String inboxItemId, String waitingFor, {required String userId});
  Future<void> processToMaybe(String inboxItemId, {required String userId});
}

Modified files

• app/lib/providers/focus_session_planning_provider.dart — inject ClarificationService via a Riverpod provider; remove direct DAO calls from clarification paths
• app/lib/database/daos/inbox_dao.dart — no logic change; called only via the service now

Tests — no new behavior to test; existing integration tests must still pass.

---

Phase 1 — Provenance Schema

Goal: establish the schema that split and merge will write into. No provenance rows are written yet — that happens in Phases 3 and 4.

Backend — Alembic migration

CREATE TABLE todo_provenance (
  id              UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  task_id         UUID        NOT NULL REFERENCES todos(id) ON DELETE CASCADE,
  source_inbox_id TEXT        NOT NULL,   -- soft ref; inbox row will be deleted
  source_title    TEXT        NOT NULL,   -- snapshot of title at clarification time
  user_id         UUID        NOT NULL,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ON todo_provenance (task_id);
CREATE INDEX ON todo_provenance (user_id);

source_inbox_id is TEXT (not a FK) because the original inbox row is deleted when consumed by a split or merge.

Provenance rows are only written for split and merge operations — ordinary 1:1 in-place promotion writes nothing. Every row in this table therefore implies a non-trivial multi-task relationship.

New files

• backend/alembic/versions/00NN_add_todo_provenance.py
• backend/app/todos/models.py — add TodoProvenance SQLAlchemy model

Client schema

Add to app/lib/database/powersync_schema.dart:

ps.Table('todo_provenance', [
  ps.Column.text('task_id'),
  ps.Column.text('source_inbox_id'),
  ps.Column.text('source_title'),
  ps.Column.text('user_id'),
  ps.Column.text('created_at'),
])

Add TodoProvenances Drift table class in the Drift schema; regenerate .g.dart.

New file: app/lib/database/daos/provenance_dao.dart

class ProvenanceDao {
  Future<void> insertProvenance(String taskId, String sourceInboxId, String sourceTitle, String userId);
  Stream<List<TodoProvenance>> watchProvenance(String taskId, String userId);
}

---

Phase 2 — Split: One Inbox Item → N Tasks

Data model

1. Insert N new todos rows (clarified = true, intent set)
2. Delete the original inbox item
3. Insert N todo_provenance rows, each pointing task_id → original inbox item id + title

All three steps in a single DB transaction.

Service layer

Add to ClarificationService:

Future<void> splitInboxItem(
  String inboxItemId,
  List<SplitTaskDraft> drafts,  // title, intent, energy, estimate, dueDate, notes
  String userId,
);

SplitTaskDraft is a plain value object. The concrete implementation is a single atomic transaction in InboxClarificationService.

UI

_ClarifyCard (inbox_clarification_step.dart) gains a secondary action:

[ Split into multiple tasks… ]   ← text button, below the PROCESS TO section

Tapping opens SplitInboxItemSheet (full-screen route — avoids keyboard/layout conflicts with ≥5 drafts).

New file: app/lib/screens/clarify/split_inbox_item_sheet.dart

Layout:

• Header showing original item title (read-only, for context)
• Scrollable list of draft rows — each has: title text field + intent chip selector (Next / Maybe / Waiting For)
• "+" button appends a new draft (pre-filled empty)
• Minimum 2 drafts required before confirm is enabled
• "Create N tasks" confirm button at bottom
• On confirm → calls ClarificationService.splitInboxItem → closes route → inbox updates reactively

Tests

• E2E: capture 1 inbox item → split into 3 → verify 3 clarified tasks exist, original inbox row gone, 3 provenance rows recorded
• Unit: SplitInboxItemSheet — confirm disabled when < 2 drafts, enabled at 2+
• Integration: InboxClarificationService.splitInboxItem is atomic (failure mid-transaction leaves inbox item intact, no provenance written)

---

Phase 3 — Merge: N Inbox Items → One Task

Data model

1. Insert 1 new todos row (clarified = true)
2. Delete all N source inbox items
3. Insert N todo_provenance rows, each linking the merged task to one source inbox item

Merge consumes (deletes) the source inbox items — they disappear from the inbox immediately. The provenance table preserves their titles as a record.

Service layer

Add to ClarificationService:

Future<void> mergeInboxItems(
  List<String> inboxItemIds,
  MergedTaskDraft draft,  // final title, notes, intent, energy, estimate
  String userId,
);

UI — Inbox screen merge mode

InboxScreen gains a merge-mode toggle:

• Toggle button in the app bar (e.g. multi-select icon)
• In merge mode: items show checkboxes; app bar shows selected count; a "Merge N items" button appears at the bottom of the screen
• Selecting < 2 items keeps the button disabled

Tapping "Merge N items" opens MergeInboxItemsSheet.

New file: app/lib/screens/clarify/merge_inbox_items_sheet.dart

Layout:

• List of selected item titles (read-only)
• Editable title (pre-populated from the first selected item)
• Notes field
• Intent chip selector
• Energy / time estimate pickers
• "Create merged task" confirm button

On confirm → calls ClarificationService.mergeInboxItems → clears merge mode → inbox updates reactively.

Merge during planning ritual: deferred. The clarification step processes items one at a time (FIFO). Adding multi-select there complicates the ritual flow. Use the Inbox screen as the only merge surface for now; re-evaluate once this UX pattern is settled.

Tests

• E2E: capture 3 inbox items → open inbox → enter merge mode → select all 3 → merge → verify 1 clarified task, 3 inbox items gone, 3 provenance rows
• Integration: InboxClarificationService.mergeInboxItems is atomic
• Unit: MergeInboxItemsSheet — title pre-populated correctly, confirm disabled when title empty

---

Phase 4 — Provenance Display (Task Detail)

task_detail_screen.dart — add a "Captured from" section:

• Shown only when ProvenanceDao.watchProvenance returns at least one row (because provenance rows only exist for split/merge, this test is sufficient — no additional filtering needed)
• Collapsed by default (ExpansionTile)
• Shows source item titles as read-only chips
• Label: "Captured from N inbox item(s)"

No new files needed.

---

File Map

File	Change	Phase
app/lib/services/clarification_service.dart	New — abstract interface	0
app/lib/services/inbox_clarification_service.dart	New — concrete impl	0
app/lib/providers/focus_session_planning_provider.dart	Delegate to service	0
backend/alembic/versions/00NN_add_todo_provenance.py	New migration	1
backend/app/todos/models.py	Add TodoProvenance model	1
app/lib/database/powersync_schema.dart	Add todo_provenance table	1
app/lib/database/drift_schema.dart	Add TodoProvenances Drift table	1
app/lib/database/daos/provenance_dao.dart	New DAO	1
app/lib/database/daos/inbox_dao.dart	Called via service only	0
app/lib/screens/planning/steps/inbox_clarification_step.dart	Add "Split" affordance	2
app/lib/screens/clarify/split_inbox_item_sheet.dart	New widget	2
app/lib/screens/inbox/inbox_screen.dart	Add merge mode	3
app/lib/screens/clarify/merge_inbox_items_sheet.dart	New widget	3
app/lib/screens/task_detail/task_detail_screen.dart	"Captured from" section	4
docs/ARCHITECTURE.md	Update task domain model section	All
docs/REQUIREMENTS.md	Add split/merge requirements	All

---

Open Decisions — Requires Sign-off Before Development Begins

1. Tag inheritance on split

When splitting one inbox item into N tasks, should the source item's tags be pre-applied to all child tasks?

The referenced proposal (docs/proposals/task-model.md §6.4) does not currently exist in the repository and cannot be consulted. This is a product call that needs an explicit answer from the user before Phase 2 is implemented. The two options:

• Yes, inherit tags: each child task starts with the parent's tags; user removes unwanted ones. Friendlier for tagged projects.
• No, start clean: simpler MVP; user tags child tasks afterwards. Lower implementation risk.

No default is assumed here.

2. Split sheet surface

Full-screen route is recommended (avoids keyboard/layout conflicts with ≥5 drafts, gives headroom for reordering), but a bottom sheet is viable for the common short-list case. Flag if you have a preference.

3. Merge in planning ritual

Currently deferred to the Inbox screen only. Should the daily planning ritual's clarification step also surface a merge affordance? This would require multi-select within the FIFO card flow, which complicates the ritual. Recommend deferring and revisiting after the inbox-screen merge is shipped.

4. Provenance display threshold

The current plan shows "Captured from" whenever any provenance row exists (i.e. only for split/merge results — ordinary 1:1 clarifications show nothing). Confirm this is the desired behaviour, or specify a different threshold.

---

Implementation Order

Phase 0  →  Phase 1  →  Phase 2  →  Phase 3  →  Phase 4
(isolate)   (schema)    (split)     (merge)     (display)

Phases 0–1 have no visible UX change and can ship as an internal cleanup PR. Phases 2 and 3 can ship independently once Phase 1 is merged. Phase 4 is a no-op until at least one split or merge has been performed.

[capo-the-ai-bot]

@TMaYaD — Trixy's revised plan addresses the feedback. Summary of what's being proposed:

Scope: Provenance is a split/merge audit log only. Ordinary 1:1 in-place promotion writes nothing. Phase 2 (the original "1:1 clarification with provenance") was removed entirely.

Status header at the top makes clear nothing is implemented yet.

Data model: Single provenance table linking parent → child task IDs with operation type (split/merge) and timestamp. Phase 4 (display) only renders when ProvenanceDao.watchProvenance returns ≥1 row, which is sufficient because rows only exist for split/merge.

Open Decision needing your sign-off (blocks Phase 2 of the engineering rollout):

Tag inheritance on split/merge — when a task splits into N children, do children inherit the parent's tags? When N tasks merge into one, are tags unioned, intersected, or reset?

Trixy notes the referenced docs/proposals/task-model.md §6.4 doesn't exist in the repo and listed both options without picking a default. This is a product call.

I've dropped ready-for-planning. Plan stands as a proposal pending your call on tag inheritance.