Skip to content

docs(task): Clarify --due is a server-side pass-through#347

Merged
engfragui merged 4 commits into
mainfrom
francesca/recurring-due-date-quick-add
May 20, 2026
Merged

docs(task): Clarify --due is a server-side pass-through#347
engfragui merged 4 commits into
mainfrom
francesca/recurring-due-date-quick-add

Conversation

@engfragui
Copy link
Copy Markdown
Contributor

@engfragui engfragui commented May 18, 2026

Background

Adds documentation/clarification re: #342.

The --due value on task add / task update is sent verbatim as due_string to the Backend API (the CLI does not parse or rewrite it), i.e. does not handle starting <date> clauses as the user might expect: 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.

Reference

…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>
@engfragui engfragui self-assigned this May 18, 2026
@doistbot doistbot requested a review from gnapse May 18, 2026 08:43
Copy link
Copy Markdown
Member

@doistbot doistbot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Share FeedbackReview Logs

Comment thread src/lib/skills/content.ts Outdated
Comment thread src/commands/task/index.ts
engfragui and others added 2 commits May 18, 2026 10:55
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>
@engfragui
Copy link
Copy Markdown
Contributor Author

engfragui commented May 18, 2026

@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).

@engfragui engfragui changed the title docs(task): clarify --due is a server-side pass-through; steer to quickadd docs(task): clarify --due is a server-side pass-through May 20, 2026
@engfragui engfragui changed the title docs(task): clarify --due is a server-side pass-through docs(task): Clarify --due is a server-side pass-through May 20, 2026
Tightens the `task add` Notes block and the skill bullet to state the
`due_string` caveat without prescribing `td task quickadd` — same
restraint already applied to the `task update` Notes block.

Also drops the corresponding "quick-add parser" assertion from
`task add --help` test coverage; the remaining assertions still pin
the distinctive phrases ("Notes:", "sent verbatim",
\`"starting <date>"\`).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@engfragui engfragui merged commit 048c64d into main May 20, 2026
5 checks passed
@engfragui engfragui deleted the francesca/recurring-due-date-quick-add branch May 20, 2026 21:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants