mcp-todoist

# Feature Specification: Deadline Support for Tasks **Feature Branch**: `003-support-for-deadline` **Created**: 2025-10-01 **Status**: Ready **Input**: User description: "support for deadline feature (check task ID 6f2QV8vWCvmf5RgR in todoist for details)" ## Clarifications ### Session 2025-10-01 - Q: Should the system block deadlines on recurring tasks since deadlines don't recur? → A: No, allow but warn that it's ineffective since deadlines can't recur - Q: Should the system block past deadline dates? → A: No, allow but append reminder that the deadline is in the past - Q: Should the system provide format instructions to tool callers? → A: Yes, provide clear date format guidance (YYYY-MM-DD) to minimize request rejections ## Execution Flow (main) ``` 1. Parse user description from Input → If empty: ERROR "No feature description provided" 2. Extract key concepts from description → Identify: actors, actions, data, constraints 3. For each unclear aspect: → Mark with [NEEDS CLARIFICATION: specific question] 4. Fill User Scenarios & Testing section → If no clear user flow: ERROR "Cannot determine user scenarios" 5. Generate Functional Requirements → Each requirement must be testable → Mark ambiguous requirements 6. Identify Key Entities (if data involved) 7. Run Review Checklist → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties" → If implementation details found: ERROR "Remove tech details" 8. Return: SUCCESS (spec ready for planning) ``` --- ## ⚡ Quick Guidelines - ✅ Focus on WHAT users need and WHY - ❌ Avoid HOW to implement (no tech stack, APIs, code structure) - 👥 Written for business stakeholders, not developers ### Section Requirements - **Mandatory sections**: Must be completed for every feature - **Optional sections**: Include only when relevant to the feature - When a section doesn't apply, remove it entirely (don't leave as "N/A") ### For AI Generation When creating this spec from a user prompt: 1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make 2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it 3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item 4. **Common underspecified areas**: - User types and permissions - Data retention/deletion policies - Performance targets and scale - Error handling behaviors - Integration requirements - Security/compliance needs --- ## User Scenarios & Testing ### Primary User Story AI assistants and developers need to specify completion deadlines for tasks that are distinct from start dates (due dates). Deadlines differentiate between when a task should be started (due date) and when it must be done by (deadline). This provides clearer project planning and tracking capabilities by separating task initiation from completion targets. ### Acceptance Scenarios 1. **Given** a new task is being created, **When** the user specifies both a due date and a deadline, **Then** the system stores both dates with the task and displays them distinctly 2. **Given** an existing task without a deadline, **When** the user updates the task to add a deadline, **Then** the system saves the deadline without affecting the existing due date 3. **Given** a task with a deadline, **When** the user updates or removes the deadline, **Then** the system persists the change and continues to maintain any existing due date 4. **Given** a user creates a task with only a deadline (no due date), **When** the task is saved, **Then** the system accepts and stores the deadline independently 5. **Given** a recurring task is being updated, **When** the user adds a deadline, **Then** the system saves the deadline but returns a warning that deadlines don't recur and will remain static 6. **Given** a user creates or updates a task, **When** the specified deadline date is in the past, **Then** the system saves the deadline but returns a reminder that the deadline is in the past 7. **Given** a user attempts to create or update a task with an invalid deadline format, **When** the request is submitted, **Then** the system rejects the request with a clear error message explaining the required format (YYYY-MM-DD with examples) ### Edge Cases - What happens when a deadline is set before the due date? System allows any date configuration without validation (deadline can be before, same as, or after due date) - How does the system handle deadline updates on recurring tasks? System allows deadlines on recurring tasks but returns a warning message that deadlines cannot recur and will remain static, making this often ineffective - What happens when a deadline date is in the past during task creation? System accepts past deadlines but appends a reminder message that the specified deadline is in the past - What happens when an invalid date format is provided? System rejects the request with a clear error message specifying the required YYYY-MM-DD format and providing examples (e.g., "2025-10-15") ## Requirements ### Functional Requirements - **FR-001**: System MUST allow users to specify a deadline date when creating a new task - **FR-002**: System MUST allow users to specify a deadline date when updating an existing task - **FR-003**: System MUST store deadline dates in YYYY-MM-DD format conforming to RFC 3339 - **FR-004**: System MUST maintain deadline dates independently from due dates (both can coexist on the same task) - **FR-005**: System MUST allow tasks to have only a deadline (no due date required) - **FR-006**: System MUST allow tasks to have only a due date (no deadline required) - **FR-007**: System MUST allow tasks to have both a deadline and a due date - **FR-008**: System MUST allow users to remove an existing deadline from a task - **FR-009**: System MUST validate deadline date format (YYYY-MM-DD) and reject invalid formats with clear error messages - **FR-010**: System MUST return the deadline field (with date and lang properties) when retrieving task details - **FR-010a**: System MUST provide clear format instructions (YYYY-MM-DD with examples) in tool documentation to help callers format dates correctly - **FR-011**: System MUST accept deadline dates on both recurring and non-recurring tasks (no blocking based on recurrence status) - **FR-012**: System MUST NOT perform temporal validation on deadline dates (past dates are acceptable) - **FR-013**: System MUST return a warning message when a deadline is added to a recurring task, noting that deadlines cannot recur and will remain static - **FR-014**: System MUST return a reminder message when a past deadline date is specified, alerting the user that the deadline is in the past ### Key Entities - **Task Deadline**: Represents when a task must be done by (distinct from due date which indicates when a task should be started) - Contains `date` property in YYYY-MM-DD format (RFC 3339) - Contains `lang` property (output only, currently unused in processing) - No time component or recurrence support - Can be applied to both recurring and non-recurring tasks, but deadline value itself does not recur - System warns users when deadline is added to recurring task (ineffective pattern) - System reminds users when past deadline date is specified - System validates format and provides clear error messages with format examples when invalid - Tool documentation includes format instructions and examples to minimize rejections - Optional field - tasks can exist without deadlines - Independent of due date - both fields can be present or absent - Provided as `deadline` attribute when creating or updating tasks --- ## Review & Acceptance Checklist *GATE: Automated checks run during main() execution* ### Content Quality - [x] No implementation details (languages, frameworks, APIs) - [x] Focused on user value and business needs - [x] Written for non-technical stakeholders - [x] All mandatory sections completed ### Requirement Completeness - [x] No [NEEDS CLARIFICATION] markers remain - [x] Requirements are testable and unambiguous - [x] Success criteria are measurable - [x] Scope is clearly bounded - [x] Dependencies and assumptions identified --- ## Execution Status *Updated by main() during processing* - [x] User description parsed - [x] Key concepts extracted - [x] Ambiguities resolved with official API documentation - [x] User scenarios defined - [x] Requirements generated - [x] Entities identified - [x] Review checklist passed ---