Skip to content

spec.md

Latest commit

 

History

History
175 lines (115 loc) · 10.1 KB

spec.md

File metadata and controls

175 lines (115 loc) · 10.1 KB
Raw

Feature Specification: CLI Todo Application

Feature Branch: 001-cli-todo-app Created: 2025-12-13 Status: Draft Input: User description: "Build a command-line todo application with these features:

  1. Add tasks with title (required) and description (optional)
  2. View all tasks showing ID, title, status, and description
  3. Update task title or description
  4. Delete tasks with confirmation
  5. Toggle task completion status

Requirements:

  • Tasks stored in memory (no persistence)
  • Each task has unique sequential ID starting from 1
  • Tasks can be complete or incomplete
  • Display complete tasks with [✓] and incomplete with [ ]
  • Menu-driven interface with options 1-6
  • Clear error messages for invalid inputs
  • Users can exit the application

Out of scope for Phase I:

  • File persistence
  • Multiple users
  • Priorities or due dates
  • Categories or tags
  • Search or filter"

User Scenarios & Testing (mandatory)

User Story 1 - Add New Tasks (Priority: P1)

A user wants to add new tasks to their todo list with a required title and optional description. The user opens the application, selects the add task option, enters a title, and optionally enters a description. The task is then stored in memory with a unique sequential ID starting from 1.

Why this priority: This is the foundational capability that enables all other functionality. Without the ability to add tasks, the application has no value.

Independent Test: Can be fully tested by adding tasks with different titles and descriptions and verifying they appear in the task list with correct IDs.

Acceptance Scenarios:

  1. Given the application is running, When user selects option to add task and enters a valid title, Then the task is added to the list with sequential ID and marked as incomplete
  2. Given the application is running, When user selects option to add task and enters a valid title and description, Then the task is added to the list with both title and description preserved

User Story 2 - View All Tasks (Priority: P1)

A user wants to see all their tasks with their ID, title, completion status, and description. The user selects the view tasks option and sees a formatted list showing each task's details with complete tasks marked with [✓] and incomplete tasks marked with [ ].

Why this priority: This is essential functionality that allows users to see their tasks and is required to use other features like updating or deleting tasks.

Independent Test: Can be fully tested by adding tasks and verifying they display correctly with proper formatting and status indicators.

Acceptance Scenarios:

  1. Given there are tasks in the system, When user selects option to view all tasks, Then all tasks are displayed with ID, title, status [✓] or [ ], and description
  2. Given there are both complete and incomplete tasks, When user views all tasks, Then complete tasks show [✓] and incomplete tasks show [ ] prefix

User Story 3 - Toggle Task Completion Status (Priority: P2)

A user wants to mark tasks as complete or incomplete. The user views the task list, selects a task by its ID, and toggles its completion status. The task's status changes from complete to incomplete or vice versa.

Why this priority: This is a core functionality that allows users to track their progress and manage their tasks effectively.

Independent Test: Can be fully tested by toggling task status and verifying the status changes correctly in the display.

Acceptance Scenarios:

  1. Given a task exists in the system, When user selects option to toggle task completion and provides a valid task ID, Then the task's completion status is flipped
  2. Given a task exists in the system, When user attempts to toggle with invalid task ID, Then appropriate error message is shown and no changes occur

User Story 4 - Update Task Title or Description (Priority: P2)

A user wants to modify the title or description of an existing task. The user selects the update option, provides the task ID, and enters new values for the title or description.

Why this priority: This allows users to correct mistakes or modify task details as needed, improving the usability of the application.

Independent Test: Can be fully tested by updating task details and verifying the changes persist in the system.

Acceptance Scenarios:

  1. Given a task exists in the system, When user selects option to update task and provides valid task ID and new title/description, Then the task details are updated accordingly
  2. Given user attempts to update with invalid task ID, When update is requested, Then appropriate error message is shown and no changes occur

User Story 5 - Delete Tasks with Confirmation (Priority: P3)

A user wants to remove tasks from their todo list. The user selects the delete option, provides the task ID, and confirms the deletion. The task is then removed from the system.

Why this priority: This allows users to remove completed or unwanted tasks, keeping their todo list organized.

Independent Test: Can be fully tested by deleting tasks and verifying they no longer appear in the task list.

Acceptance Scenarios:

  1. Given a task exists in the system, When user selects option to delete task, provides valid task ID, and confirms deletion, Then the task is removed from the system
  2. Given user attempts to delete with invalid task ID, When deletion is requested, Then appropriate error message is shown and no changes occur

User Story 6 - Menu-Driven Interface and Exit (Priority: P1)

A user wants to navigate the application through a menu system with options 1-6 and be able to exit cleanly. The user sees a menu with numbered options and can select an option to perform the corresponding action or exit the application.

Why this priority: This is the primary interface through which all functionality is accessed and is essential for the application to be usable.

Independent Test: Can be fully tested by navigating through all menu options and verifying the correct functionality is executed.

Acceptance Scenarios:

  1. Given the application is running, When user enters a valid menu option (1-6), Then the corresponding functionality is executed
  2. Given the application is running, When user chooses to exit, Then the application terminates cleanly
  3. Given the application is running, When user enters an invalid menu option, Then appropriate error message is shown and menu is displayed again

Edge Cases

  • What happens when user enters invalid input for task ID (non-numeric, out of range)?
  • How does system handle empty or whitespace-only titles for new tasks?
  • How does system handle invalid menu selections outside the 1-6 range?
  • What happens when user tries to update/delete a task that no longer exists after another operation?

Requirements (mandatory)

Functional Requirements

  • FR-001: System MUST store tasks in memory with no persistence to external storage
  • FR-002: System MUST assign unique sequential IDs starting from 1 to each task
  • FR-003: System MUST allow users to add tasks with required title and optional description
  • FR-004: System MUST validate task titles to be 1-100 characters in length
  • FR-005: System MUST validate task descriptions to be 0-500 characters in length
  • FR-006: System MUST display all tasks showing ID, title, status [✓/ ], and description
  • FR-007: System MUST allow users to update task title or description by ID
  • FR-008: System MUST allow users to delete tasks by ID with confirmation
  • FR-009: System MUST require "yes/no" confirmation before deleting a task
  • FR-010: System MUST allow users to toggle task completion status by ID
  • FR-011: System MUST provide a menu-driven interface with options 1-6 for different operations
  • FR-012: System MUST display complete tasks with [✓] and incomplete tasks with [ ] prefix
  • FR-013: System MUST show clear error messages for invalid inputs
  • FR-014: System MUST provide error messages that clearly state what went wrong and suggest how to fix it
  • FR-015: System MUST display a clear error message when a user enters a non-existent task ID
  • FR-016: System MUST allow users to exit the application cleanly
  • FR-017: System MUST validate task IDs and provide appropriate feedback for invalid IDs

Key Entities

  • Task: Represents a single todo item with attributes: ID (sequential integer starting from 1), title (required string), description (optional string), completion status (boolean)
  • Task List: Collection of Task entities stored in memory with functionality to add, view, update, delete, and toggle completion status

Clarifications

Session 2025-12-13

  • Q: What validation rules should apply to task titles, specifically regarding minimum/maximum length and character restrictions? → A: Titles must be 1-100 characters, no special restrictions
  • Q: What type of confirmation is required before deleting a task? → A: Simple "yes/no" prompt
  • Q: Should there be any character limits on the optional task description field? → A: Descriptions should be limited to 500 characters
  • Q: How specific should error messages be when users provide invalid input? → A: Error messages should clearly state what went wrong and suggest how to fix it
  • Q: What should happen when a user enters a task ID that is syntactically valid (number) but doesn't exist in the system? → A: Display a clear error message that the task ID doesn't exist

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: Users can add, view, update, delete, and toggle task completion with 100% success rate for valid inputs
  • SC-002: Users can complete any task operation within 30 seconds of starting the interaction
  • SC-003: All error conditions are handled gracefully with clear user-friendly error messages displayed
  • SC-004: The menu-driven interface responds to user input immediately with no more than 1 second delay
  • SC-005: The application maintains all tasks in memory during the session with 100% data integrity