docs(task): clarify --due is a server-side pass-through; steer to quickadd#347
docs(task): clarify --due is a server-side pass-through; steer to quickadd#347engfragui wants to merge 3 commits into
--due is a server-side pass-through; steer to quickadd#347Conversation
…ckadd The --due value on `task add` / `task update` is sent verbatim as `due_string`; the CLI does not parse or rewrite it. Todoist's server `due_string` parser handles simple inputs but does NOT consume `starting <date>` clauses — strings like `every! 2 weeks starting 2026-05-17` end up stored as the entire literal recurrence rule and the task never advances on completion. The quick-add parser does consume `starting` correctly. Document this in three places users actually hit: - `task add --due` help: shorter description + a Notes block on `td task add --help` describing the failure mode and pointing to `td task quickadd` as the right command for NL recurrence. - `task update --due` help: same pass-through note, referring back to `td task add --help`. - Skill content (`src/lib/skills/content.ts`) — adds a bullet to the existing "Choosing between task add and task quickadd" guidance. Regenerated `skills/todoist-cli/SKILL.md` via `npm run sync:skill`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
doistbot
left a comment
There was a problem hiding this comment.
Thank you for adding this helpful documentation to clarify the --due parsing limitations and steering users toward the natural language capabilities of quickadd. This update will significantly reduce user frustration around complex recurrence rules. A couple of adjustments were flagged during review, specifically regarding the need to scope the quickadd recommendation strictly to task creation rather than updates, as well as the need for test coverage of the help output in task.test.ts to ensure the new guidance is preserved.
Follow-up to fe745a7. Mirrors the same `due_string` caveat into `td task update --help` via an addHelpText('after', ...) block, and points users at `td task reschedule` as the way to move the next occurrence of a recurring task without disturbing the recurrence rule. Also pulls the manual tightening of the SKILL.md bullet back into `src/lib/skills/content.ts` so future `npm run sync:skill` runs stay consistent with the shorter wording. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Addresses doistbot's P2 review comment: the prior commits added the "--due is sent verbatim" Notes blocks to `td task add --help` and `td task update --help` but had no regression coverage, so a future Commander/help refactor could silently drop the guidance. Adds a new describe block in `src/commands/task/task.test.ts` that captures `--help` output for both subcommands and asserts the key phrases stay present: - `task add --help`: "Notes:", "sent verbatim", `"starting <date>"`, "quick-add parser". - `task update --help`: "Notes:", "sent verbatim", `"starting <date>"`, "same caveats as", `"task add --due"`. Also finalises the surrounding copy that the tests pin: - `task update --help` Notes block drops the `task reschedule` recommendation (reschedule is for moving the next occurrence without changing the recurrence rule — orthogonal to the `due_string` caveat the block is about). - Skill bullet (`src/lib/skills/content.ts`, regenerated `skills/todoist-cli/SKILL.md`) scopes the `td task quickadd` recommendation to new-task creation, since quickadd can't replace an update. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
|
@scottlovegrove Apologies, I keep forgetting we automatically add a review right away to PRs in this repo, so I guess it tagged you when I was still working on the PR (edit: it actually tagged Ernesto and you were just a lurker!). Either way, I'm done now (just did a little re-wording, nothing much). |
Background
The
--duevalue ontask add/task updateis sent verbatim asdue_stringto the Backend API (the CLI does not parse or rewrite it), i.e. does not handlestarting <date>clauses as the user might expect: strings likeevery! 2 weeks starting 2026-05-17end up stored as the entire literal recurrence rule and the task never advances on completion.However note that the quick-add parser does consume
startingcorrectly/as the user expects.This PR
Document this in three places users actually hit:
task add --duehelp: shorter description + a Notes block ontd task add --helpdescribing the failure mode and pointing totd task quickaddas the right command for NL recurrencetask update --duehelp: same pass-through note, referring back totd task add --helpsrc/lib/skills/content.ts) — adds a bullet to the existing "Choosing between task add and task quickadd" guidance. Regeneratedskills/todoist-cli/SKILL.mdvianpm run sync:skillReference
Helps with #342