From 56cd7195060e7ac304cba946087d5f56d5a5f187 Mon Sep 17 00:00:00 2001 From: Peter Stone Date: Wed, 15 Jul 2026 10:15:56 +0000 Subject: Add design docs for four backlog task-scheduling ideas Labels/projects, budgets/availability, recurring maintenance buckets, and linear task chains -- refined via a 24-question interview (2026-07-15) into concrete data models, mechanisms, and API shapes. None approved for implementation yet; each spec notes its dependencies on the others (labels/projects is foundational to two of the other three). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01VTUSAEKfsPc6WGDq45yPHD --- ...6-07-15-task-budgets-and-availability-design.md | 64 ++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-15-task-budgets-and-availability-design.md (limited to 'docs/superpowers/specs/2026-07-15-task-budgets-and-availability-design.md') diff --git a/docs/superpowers/specs/2026-07-15-task-budgets-and-availability-design.md b/docs/superpowers/specs/2026-07-15-task-budgets-and-availability-design.md new file mode 100644 index 0000000..923ef54 --- /dev/null +++ b/docs/superpowers/specs/2026-07-15-task-budgets-and-availability-design.md @@ -0,0 +1,64 @@ +# Task Budgets and Availability Times — Design + +**Status:** Backlog idea, refined via interview 2026-07-15. Not yet approved for implementation. + +## Context + +The goal is to know whether what's on your plate actually fits in the time you realistically have, without doot trying to auto-schedule your day for you. This is explicitly a **visibility** feature, not a **scheduling** one, per the interview. + +**Depends on:** [[doot-future-task-scheduling-ideas]] item 2 (task labels/projects) — availability tracking is opt-in per project/label, so that feature needs to exist first. + +## Scope + +doot-native tasks only. Opt-in: a project or label is marked as "budget-tracked," and only tasks under a tracked project/label count against any budget calculation. Untracked tasks are invisible to this whole feature — the default experience is unchanged. + +## Data Model + +**Availability** — a manual recurring weekly template, reduced by real calendar events: +```sql +CREATE TABLE availability_blocks ( + id TEXT PRIMARY KEY, + weekday INTEGER NOT NULL, -- 0-6, Sun-Sat + start_time TEXT NOT NULL, -- "18:00" + end_time TEXT NOT NULL, -- "20:00" + label TEXT DEFAULT '' -- optional, e.g. "evening focus time" +); +``` +At computation time (see below), a day's available minutes = sum of that weekday's `availability_blocks` minus any overlapping existing calendar events (already fetched via `BuildTimeline` — no new calendar integration needed, just a subtraction pass over blocks the timeline already has). + +**Budget** — both per-task estimate and a period pool, per the interview: +- `native_tasks` gets `estimated_minutes INTEGER DEFAULT 0` — user-entered or inferred (see below). +- A period pool isn't a separate stored number — it's *computed* as the sum of `availability_blocks` for the period (today, this week), and compared against the sum of `estimated_minutes` for all budget-tracked, incomplete, due-in-period tasks. No new "pool" table; the pool is availability itself. + +**Estimate inference ("learned from history"):** requires tracking actual completion duration, which doot doesn't currently record (tasks have `due_date`/`completed_at` but no "started working on this" timestamp). The simplest version that doesn't require a new "time tracking" UI: when a task completes, if it had no `estimated_minutes` set, backfill nothing (no signal to learn from) — but if a *label* or *project* accumulates several tasks with user-entered `estimated_minutes`, use the average of the same-label/project tasks' user-entered estimates as the default for a *new* task under that label/project, rather than inferring from actual elapsed time. This sidesteps needing real time-tracking infrastructure while still delivering "the system learns typical durations for this kind of task." True elapsed-time-based learning is a larger, separate feature not designed here. + +## Computation and Surfacing + +No new background job — this is computed on read, at the same points `BuildTimeline`/`HandleWidgetGet` already run: +1. For "today" and "this week," sum `estimated_minutes` across budget-tracked incomplete tasks due in that window. +2. Sum available minutes from `availability_blocks` for the matching weekdays, minus overlapping calendar events already in the timeline. +3. If load > availability, surface a flag — not a hard block, not a reorder. Likely surfaced as a small indicator in the web timeline (e.g. "6.5h scheduled / 4h available today") and, if there's room, a small badge on the widget's TODAY header. Exact placement is a UI-design decision for the implementation plan, not fixed here. + +Per the interview: **no auto-scheduling, no auto-reprioritization** — the flag is purely informational. + +## API + +- `GET/POST /api/widget/availability` — CRUD for `availability_blocks`. +- `POST /api/widget/task/estimate` — `{id, estimated_minutes}`. +- The overflow flag itself doesn't need a dedicated endpoint — it's computed as part of the existing `GET /api/widget` and the web timeline's existing data-building path, added as a new field on the response (e.g. `budget_status: {scheduled_minutes, available_minutes}` alongside `items`). + +## Recurrence Interaction + +`estimated_minutes` is task-level, not series-level — the interview didn't ask about this directly, but since it's meant to reflect "how long does *this kind* of task take," and `CreateNextIteration` already copies most fields forward, the natural default is to carry it forward like content/description/project/labels. Re-estimating a specific occurrence would just mean editing that occurrence's value directly (no override mechanism needed beyond the normal edit UI). + +## Testing + +Store-layer tests for availability CRUD and the availability-minus-calendar-events computation (a pure function, easy to unit test with fixture events). Handler tests for the new endpoints and for the `budget_status` field appearing correctly in `/api/widget`'s response only when budget-tracked tasks exist. + +## Out of Scope + +- Auto-scheduling tasks into specific time slots. +- Auto-reprioritization or auto-deferral on overflow. +- Real elapsed-time tracking (start/stop timers) — estimate inference uses same-label/project averaging of user-entered values instead. +- Any UI beyond a basic indicator — exact visual treatment is an implementation-time decision. +- Non-project/label-scoped (global) budgets — everything is opt-in per the interview. -- cgit v1.2.3