personal memory agent
todos: document nudge family — --nudge flag, list-nudges-due, dispatch-nudges
Nudge scheduling (call.py:120-149, 441, 490) was live but the skill only
documented basic add/done/cancel/move. Add the --nudge/-n flag to the
add section with the four accepted formats, then add list-nudges-due
and dispatch-nudges as full sections. Also add a Gotchas block for the
fuzzy-duplicate silent-rejection behavior and the read/mutate split
between list-nudges-due and dispatch-nudges.
Plus Invoke via Bash and expanded TRIGGER.
Part of skills audit req_loq3e2lk pass 1+2.
+63
-6
+63
-6
apps/todos/talent/todos/SKILL.md
+63
-6
apps/todos/talent/todos/SKILL.md
···
2
2
name: todos
3
3
description: >
4
4
Manage todo checklists organized by facet and day. List, add, complete,
5
-
cancel, and move tasks and action items. Review upcoming scheduled items.
5
+
cancel, move tasks, schedule nudges (reminders), and review upcoming items.
6
6
Use when the owner mentions tasks, to-do items, action items, checklists,
7
-
or reminders, or asks to add, complete, cancel, or review todos.
8
-
TRIGGER: todo, task, action item, checklist, reminder, upcoming items.
7
+
reminders, or nudges, or asks to add, complete, cancel, or review todos.
8
+
TRIGGER: todo, task, action item, checklist, reminder, nudge, scheduled
9
+
reminder, upcoming items, remind me, sol call todos list,
10
+
sol call todos add, sol call todos done, sol call todos cancel,
11
+
sol call todos upcoming, sol call todos list-nudges-due,
12
+
sol call todos dispatch-nudges.
9
13
---
10
14
11
15
# Todos CLI Skill
12
16
13
-
Use these commands to manage checklist entries from the terminal.
17
+
Manage checklist entries and reminders. Invoke via Bash: `sol call todos <command> [args...]`.
14
18
15
19
**Environment defaults**: When `SOL_DAY` is set, commands that take a DAY argument will use it automatically. Same for `SOL_FACET` where FACET is required.
16
20
···
48
52
## add
49
53
50
54
```bash
51
-
sol call todos add TEXT [-d DAY] [-f FACET] [--force]
55
+
sol call todos add TEXT [-d DAY] [-f FACET] [-n NUDGE] [--force]
52
56
```
53
57
54
-
Add a new todo item.
58
+
Add a new todo item, optionally with a nudge (reminder).
55
59
56
60
- `TEXT`: todo text (positional argument).
57
61
- `-d, --day`: day in `YYYYMMDD` (default: `SOL_DAY` env).
58
62
- `-f, --facet`: facet name (default: `SOL_FACET` env).
63
+
- `-n, --nudge`: optional reminder time. Accepted formats: `HH:MM` (today), `tomorrow HH:MM`, `YYYYMMDDTHH:MM` (absolute), or `now`.
64
+
- `--force`: skip the cross-facet duplicate check.
59
65
60
66
Behavior notes:
61
67
···
69
75
```bash
70
76
sol call todos add "Draft Q1 plan" -d 20260115 -f work
71
77
sol call todos add "Team sync prep (14:30)" -d 20260115 -f work
78
+
sol call todos add "Call Alicia back" -f work -n "15:30"
79
+
sol call todos add "Submit expense report" -f work -n "tomorrow 09:00"
72
80
```
73
81
74
82
## done
···
152
160
```bash
153
161
sol call todos move 3 --day 20260115 --from personal --to work --consent
154
162
```
163
+
164
+
## list-nudges-due
165
+
166
+
```bash
167
+
sol call todos list-nudges-due [-f FACET] [--json]
168
+
```
169
+
170
+
List todo items whose nudge time is due and have not yet been notified.
171
+
172
+
- `-f, --facet`: optional facet filter. Omit to check all facets.
173
+
- `--json`: emit JSON for programmatic use.
174
+
175
+
Behavior notes:
176
+
177
+
- Reads state only; does not mark items as notified or send notifications.
178
+
- Groups by facet when multiple facets have due items.
179
+
180
+
Example:
181
+
182
+
```bash
183
+
sol call todos list-nudges-due
184
+
sol call todos list-nudges-due -f work --json
185
+
```
186
+
187
+
## dispatch-nudges
188
+
189
+
```bash
190
+
sol call todos dispatch-nudges [-f FACET]
191
+
```
192
+
193
+
Send desktop notifications for all due, unnotified nudges and mark them notified so they won't fire again.
194
+
195
+
- `-f, --facet`: optional facet filter. Omit to dispatch for all facets.
196
+
197
+
Behavior notes:
198
+
199
+
- Uses `sol notify` to deliver. Each successful dispatch updates the item's notified state.
200
+
- Intended for a periodic caller (routine or launchd); manual invocation is fine for testing.
201
+
202
+
Example:
203
+
204
+
```bash
205
+
sol call todos dispatch-nudges
206
+
```
207
+
208
+
## Gotchas
209
+
210
+
- **Duplicate-check is fuzzy and silent-looking.** `add` rejects items with ≥70% similarity to an existing item across other facets within ±1 day. The rejection prints matches to stderr; if you miss the message, the add looks like it silently failed. Pass `--force` when you know the duplication is intentional.
211
+
- **`list-nudges-due` is non-mutating; `dispatch-nudges` marks notified.** Don't expect `list-nudges-due` to clear the queue — use it for inspection.