Weekly Review's Waiting For / Someday → Next promotion leaves tasks actionless

[TMaYaD]

Problem

When the Weekly Review wizard promotes a task to Next from Waiting For or Someday/Maybe, the routing writes intent='next' but leaves next_action_text unchanged (typically NULL). The user just decided this task is actionable — but didn't say what the action is. The task lands on the Next Actions list immediately, actionless, and then surfaces in the daily re-clarification queue (_needsReviewWhere, todo_dao.dart:383-393) until the user re-processes it. Avoidable round-trip.

The pattern is established elsewhere in the codebase:

• Inbox → Next already mirrors the title into next_action_text via InboxClarifyCard's title-as-action coupling (ARCHITECTURE.md:413).
• DPR task-review step already uses the ProcessAction.nextActionDialog modifier to force a phrase when updating a next action (task_review_step.dart:183, dialog at next_action_dialog.dart).

The weekly review's Waiting For and Someday/Maybe steps just haven't been wired up the same way.

Audit of promotion-to-Next paths in the Weekly Review

Step	Config	Promotes to Next?	Prompts for text?
Inbox	InboxClarifyCard	Yes	Yes (title mirror)
Waiting For	waiting_for_step.dart:62-65 include:{keep}, except:{waitingFor}	Yes (plain next in defaults)	No
Next Actions (after #290)	except:{next}	N/A (already on list)	—
Someday/Maybe	someday_maybe_step.dart:59-66 include:{keep} (plain next in defaults)	Yes	No

Proposed fix

In waiting_for_step.dart and someday_maybe_step.dart, swap the plain Next default for the dialog modifier:

process: ProcessToHandlers(
  todo: todo,
  include: const {ProcessAction.keep, ProcessAction.nextActionDialog},
  except: const {ProcessAction.next, ProcessAction.waitingFor /* or someday */},
  ...
  onAfterRoute: (action) async {
    if (action == ProcessAction.nextActionDialog) {
      // Same pattern as task_review_step.dart:194-210:
      // read back the persisted text; if blank, don't record routing;
      // otherwise record as a `next` routing for the step's stats.
      ...
    }
    // existing branches
  },
),

The dialog opens prefilled with whatever (if anything) is on next_action_text, the user types a phrase, save writes the new text + stamps last_clarified_at (per setNextActionText at todo_dao.dart:367-377), and the wizard records a Next routing for waitingForRoutings / somedayRoutings. If the user clears the field and saves blank, no routing is recorded and the step stays on the current item (same pattern task_review_step.dart:201-204 uses).

Test plan

• Widget test: tapping "Next" on a Waiting For item opens NextActionDialog. Saving a phrase writes next_action_text, intent='next', and clears the person tag (current behaviour — confirm not regressed via the orthogonality invariant) — actually do NOT strip the person tag, per the existing intent ⊥ delegate rule (ARCHITECTURE.md:396); if the user wants the delegate gone, they remove it explicitly.
• Widget test: tapping "Next" on a Someday item opens the dialog. Saving routes to Next with the phrase.
• Widget test: clearing the dialog and saving blank does NOT route the task and the wizard stays on the same item.
• Integration: after the weekly review, the daily re-clarification queue (getNeedsReview) does NOT include items that were promoted via this dialog (because next_action_text is set and last_clarified_at is fresh).
• flutter analyze clean.

Related

• Daily re-clarification surface floods with waiting-for tasks as "actionless" #289 — daily re-clarification surface fatigue (this issue cuts the source of actionless tasks).
• Rename Weekly Review's "Projects" step to "Next Actions" and broaden snapshot #290 — Weekly Review's Next Actions step rename.

[trixy-the-ai-bot]

Implementation Plan — Issue #293: Weekly Review Waiting For / Someday → Next promotion leaves tasks actionless

Goal

When a user promotes a Waiting For or Someday/Maybe item to Next in the Weekly Review wizard, force them to name the next action via NextActionDialog. This stops freshly-promoted tasks landing actionless on the Next list and re-surfacing in the daily re-clarification queue.

Audit result — make nextActionDialog a default, not opt-in

Per the feedback, I audited every ProcessToHandlers callsite that renders a next button:

Callsite	Renders next?	Wants dialog on next?
task_review_step.dart:226	Yes	Yes — opts in via include today
waiting_for_step.dart:62	Yes	Yes — this issue
someday_maybe_step.dart:59	Yes	Yes — this issue
inbox_clarify_card.dart:320	Yes	No — has its own title-as-action coupling in onAfterRoute
next_actions_step.dart:66	No (except:{next})	N/A

3 of the 4 next-rendering callsites want the dialog; the lone exception (inbox) deliberately uses a different mechanism (mirror the live title into next_action_text). So the safe behavior — promoting to Next always captures a phrase — should be the default, with inbox opting out via except. This also fixes the issue's buggy proposed snippet (except:{next} would delete the Next button entirely and leave nothing to open the dialog).

Changes

1. app/lib/widgets/process_to_handlers.dart — flip the default

• Add ProcessAction.nextActionDialog to _kDefaultActions. It now participates in include/except resolution like any other action. (_renderableActions() already strips it from the rendered button list — keep that line; it's a modifier, never its own button.)
• Change the _onTap next branch: instead of widget.include.contains(ProcessAction.nextActionDialog), check the resolved action set (_kDefaultActions ∪ include − except) for nextActionDialog. Extract a small _dialogModifierActive helper so _onTap and any future caller share one definition.
• Update the doc comments on the ProcessAction enum (lines ~29-31), include (~140), except (~144-148), and onAfterRoute (~176) to state the modifier is on by default and removed via except.

2. app/lib/widgets/inbox_clarify_card.dart — opt out

• Add except: const {ProcessAction.nextActionDialog} to the ProcessToHandlers call. Inbox keeps its current one-tap Next behavior (title mirrored into next_action_text by its own onAfterRoute); without the opt-out, tapping Next would now pop a dialog — an unintended UX change to inbox clarification.
• Update the adjacent comment (lines 329-335) to say the dialog modifier is excepted here because the title-as-action coupling already supplies the phrase.

3. app/lib/screens/periodic_review/steps/waiting_for_step.dart

• Add import for database_provider.dart (to read back the persisted text).
• ProcessToHandlers:
  • include: unchanged — {ProcessAction.keep}. (No need to add nextActionDialog — it's now a default.)
  • except: unchanged — {ProcessAction.waitingFor}.
  • labels: add ProcessAction.next: 'Next Action…' — the ellipsis signals the button opens a dialog (sanctioned by the ProcessToHandlers.labels doc).
• onAfterRoute: add a nextActionDialog branch mirroring task_review_step.dart:241-257:
  • Read back the todo via ref.read(databaseProvider).todoDao.getTodo(todo.id).
  • If nextActionText?.trim() is empty → return without recording a routing or advancing (blank save; stay on the item — matches task_review_step.dart:248-251).
  • Otherwise notifier.recordWaitingForRouting(index, RoutingKind.nextAction) then notifier.advanceWaitingFor().
  • Keep the existing keep branch and the generic kind = action.toRoutingKind() branch for someday / done / trash.
• Note: dialog cancel never calls onAfterRoute (_nextWithDialog returns early) — wizard correctly stays put.

4. app/lib/screens/periodic_review/steps/someday_maybe_step.dart

Identical treatment:

• Add database_provider.dart import.
• include unchanged {ProcessAction.keep}; except unchanged {waitingFor, someday, done}.
• labels: add ProcessAction.next: 'Next Action…'.
• onAfterRoute: add the same nextActionDialog branch, using recordSomedayRouting / advanceSomeday.

5. app/lib/screens/planning/steps/task_review_step.dart — simplify

• Remove ProcessAction.nextActionDialog from include (now redundant — it's a default). Keep if (showKeep) ProcessAction.keep. Behavior and the onAfterRoute nextActionDialog branch are unchanged.

6. app/lib/screens/periodic_review/steps/next_actions_step.dart — optional tidy

• except:{next} already makes the modifier inert (no Next button to trigger it). Optionally add ProcessAction.nextActionDialog to except so the resolved set reads cleanly. Low priority; leave a one-line comment either way.

7. Docs

• docs/ARCHITECTURE.md: update the weekly-review step descriptions and the title-as-action / intent⊥delegate sections (issue refs :396, :413). State that promoting to Next from Waiting For / Someday now captures a phrase via the dialog, and that the dialog modifier is ProcessToHandlers' default with inbox opting out. Rewrite stale claims; no changelog notes.
• NOTES.md: one-line entry under today's date — nextActionDialog flipped to default-on after auditing callsites; inbox opts out via except.

Tests (TDD — write first, watch fail, then implement)

app/test/widgets/process_to_handlers_test.dart (update existing):

• The nextActionDialog modifier group (lines ~401-461, ~660-683): the modifier now fires without include: {nextActionDialog}. Add a case asserting except: {nextActionDialog} reverts to plain next (immediate route, no dialog).

New app/test/screens/periodic_review/steps/waiting_for_step_test.dart
Harness: ProviderScope with databaseProvider overridden to in-memory GtdDatabase, pump the step in MaterialApp/Scaffold, grab the container via ProviderScope.containerOf, call notifier.loadWaitingForSnapshot(), pumpAndSettle. Model on task_review_step_waiting_for_test.dart.

• Tapping "Next Action…" opens NextActionDialog.
• Phrase + Save writes next_action_text, sets intent='next', and leaves the person tag attached (assert todo_tags row still exists — intent⊥delegate not regressed); records a Next routing in waitingForRoutings and advances.
• Blank save records no routing and the wizard stays on the same item (waitingForRoutings unchanged, waitingForNav.index unchanged).
• Cancel: no routing, no advance.

New app/test/screens/periodic_review/steps/someday_maybe_step_test.dart

• "Next Action…" opens the dialog; phrase + Save routes to Next (intent='next', next_action_text set) and records somedayRoutings.
• Blank save does not route; wizard stays.

Integration (periodic_review_flow_test.dart, widget-driven):

• After promoting a Waiting For / Someday item to Next via the dialog with a phrase, db.todoDao.getNeedsReview() does not include that task (next_action_text set + last_clarified_at fresh exclude it from both _needsReviewWhere branches).

Regression — inbox unchanged: confirm inbox_clarify_screen_test.dart still passes (Next stays one-tap; no dialog appears). Add an assertion that tapping Next on an inbox item does not open NextActionDialog if not already covered.

Static analysis: flutter analyze clean.

Verification

1. cd app && flutter analyze
2. cd app && flutter test test/widgets/process_to_handlers_test.dart test/screens/periodic_review/ test/screens/inbox/ test/screens/planning/ test/integration/periodic_review_flow_test.dart
3. Full suite for regressions: cd app && flutter test

Out of scope

• Adding a dialog to the Inbox step — inbox keeps its title-as-action coupling and opts out.
• Changes to NextActionDialog or applyRouting — the existing dialog path already does exactly what's needed.

[TMaYaD]

Review if it makes sense to still hide next action dialog by default. With this change, most next buttons should include the dialog as well. Verify. If it turns out to be the case, show by default and hide as except.

[trixy-the-ai-bot]

Revision note:

Audited all five ProcessToHandlers callsites: of the four that render a next button, three want the dialog and only inbox_clarify_card (which has its own title-mirror coupling) does not — so I flipped the plan to make nextActionDialog a default in ProcessToHandlers, with inbox opting out via except. This simplifies task_review_step, waiting_for_step, and someday_maybe_step, but expands the blast radius beyond the original two-file change to touch the core widget, inbox_clarify_card, and process_to_handlers_test.dart. One push-back: this couples a wider refactor to issue #293 — if you'd rather keep #293 surgical, I can instead just add nextActionDialog to include in the two weekly-review steps (the original plan) and file the default-flip as a separate follow-up.

[trixy-the-ai-bot]

Implementation complete.

Issue #293 was implemented by flipping nextActionDialog to default-on in process_to_handlers.dart (with a new resolved-set helper), opting out at callsites that don't need it (InboxClarifyCard, NextActionsStep), and wiring the dialog into WaitingForStep and SomedayMaybeStep so weekly-review promotions capture a Next Action phrase. Docs (ARCHITECTURE.md, NOTES.md) were updated, and verification passed: flutter analyze clean and all 669 tests green, including new coverage for the two promotion steps and a regression test for InboxClarifyCard. Nothing has been committed or pushed yet.