Skip to content

docs(task): clarify --due is a server-side pass-through; steer to quickadd#347

Open
engfragui wants to merge 3 commits into
mainfrom
francesca/recurring-due-date-quick-add
Open

docs(task): clarify --due is a server-side pass-through; steer to quickadd#347
engfragui wants to merge 3 commits into
mainfrom
francesca/recurring-due-date-quick-add

Conversation

@engfragui
Copy link
Copy Markdown
Contributor

@engfragui engfragui commented May 18, 2026

Background

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.

However note that the quick-add parser does consume starting correctly/as the user expects.

This PR

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

Reference

Helps with #342

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

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