Skip to content

PRD-005: Issue Tracking

Field Value
ID PRD-005
Title Issue Tracking
Status Draft
Owner Loryth Team
Created 2026-02-18

1. Problem Statement

Personal task management tools are either too simple (plain to-do lists without workflows) or too complex (enterprise project management with features individuals don't need). Self-hosted options like Vikunja or WeKan provide board views but lack configurable workflows, issue type differentiation, and hierarchical task decomposition. Users who manage personal projects, household tasks, and hobby work need a flexible system that adapts to different processes without enterprise overhead.

Loryth's issues service provides project-based issue tracking with configurable workflows, custom issue types, hierarchical parent-child issues, and event-sourced activity history.

2. Target Personas

Persona Priority Relevance
Self-Hosting Tinkerer Primary Personal project management, software development tracking
Household Coordinator Secondary Family chore assignments and household task tracking

3. User Stories

ID Story Priority
US-ISS-001 Create and manage issues Must
US-ISS-002 Configure workflows Must
US-ISS-003 Define issue types Should
US-ISS-004 Organize issues hierarchically Should
US-ISS-005 Manage projects Must
US-ISS-006 Assign household tasks Should
US-ISS-007 View issue activity history Should

4. Functional Requirements

ID Requirement Priority
FR-1 CRUD operations for issues with title, description, type, and status Must
FR-2 Project management with name, description, and CMS node linkage Must
FR-3 Custom workflow definitions with named statuses and allowed transitions Must
FR-4 Issue types with name, UI metadata (icon, color), and workflow linkage Should
FR-5 Workflow transition validation preventing invalid status changes Must
FR-6 Hierarchical issues via self-referencing parent_id Should
FR-7 Issue assignment to user accounts with optional due dates Should
FR-8 Event-sourced activity history: IssueCreated, IssueStatusChanged, IssueProjectChanged, IssueParentChanged Should
FR-9 Status UI metadata (icon, color) for visual differentiation in board views Should

5. Non-Functional Requirements

  • Issue list must load in under 300ms for projects with up to 1,000 issues
  • Workflow transition validation must be enforced at the domain level, not just the API
  • Event history must be append-only and immutable

6. Acceptance Criteria

  • User can create projects, issue types, and workflows (FR-1, FR-2, FR-3, FR-4)
  • Issues can only transition through workflow-defined paths (FR-5)
  • Parent-child issue hierarchy works with navigation between levels (FR-6)
  • Issues can be assigned with due dates and filtered by assignee (FR-7)
  • Activity history shows all status and project changes with timestamps (FR-8)

7. Out of Scope

  • Kanban board UI (tracked separately in UI roadmap)
  • Time tracking or effort estimation
  • Sprint planning or agile ceremony support
  • External integrations (GitHub, GitLab, Jira import)
  • File attachments on issues (handled via CMS linkage)

8. Traceability

Artifact Reference
Vision Vision — "task management" as a core domain
Roadmap Release 0.2
Stories Issues Stories

9. Open Questions

  • Should workflows support automatic transitions (e.g., auto-close parent when all children done)?
  • How should board views handle issues with no workflow (e.g., simple flat task lists)?
  • Should issue notifications be configurable per-project or global?

10. Changelog

Date Change
2026-02-18 Initial version